An Overview of the Server

The Role of the Server

The webMethods Integration Server hosts packages that contain services and related files. The Integration Server comes with core Integration Server packages. For example, all Integration Server instances include packages that contain built-in services that your developers might want to invoke from their services or client applications and services that demonstrate some of the features of the Integration Server. You can create additional packages to hold the services that your developers create. Your developers can create services that perform functions, such as integrating your business systems with those of your partners, retrieving data from legacy systems, and accessing and updating databases.

webMethods Integration Server provides an environment for the orderly, efficient, and secure execution of services. It decodes client requests, identifies the requested services, invokes the services, passes data to them in the expected format, encodes the output produced by the services, and returns output to the clients.

Additionally, the server authenticates clients, verifies that they are authorized to execute the requested service, maintains audit-trail logs, and promotes throughput using facilities such as service result caching.

About Integration Server Instances

webMethods Integration Server allows you to create and run multiple instances of the server on one machine. When you install webMethods Integration Server, you specify a name for the initial instance. The default name of the initial instance is “default”. The Software AG installer creates the instance under the Software AG_directory \IntegrationServer\instances directory. You can create additional instances of Integration Server using the scripts provided by Integration Server or through Software AG Command Central.

Each instance has a home directory under Software AG_directory \IntegrationServer\instances that contains its own packages, configuration files, log files, and updates. You administer and apply packages and updates to each Integration Server instance separately. You can apply the latest fixes using the Software AG Update Manager.

The Software AG_directory \IntegrationServer directory is the parent directory for all server instances you create. It contains common and shared files that all server instances use, such as common jar files and fixes. For information about creating and running multiple Integration Server instances, see Running Multiple Integration Server Instances.

Note: Unless otherwise specified, the terms Integration Server and “the server” in this guide refer to an Integration Server instance.

Architecture

The Integration Server listens for client requests on one or more ports. You can associate the type of protocol that the server uses for each port. The server supports HTTP, HTTPS, FTP, FTPS, and e-mail ports.

Most clients use an HTTP or HTTPS port for communication with the server. Because the server supports both HTTP and HTTPS, it can listen on an HTTP port for non-secure client requests and an HTTPS port for secure requests.

Note: Unlike HTTP, FTP, and e-mail, HTTPS and FTPS provide for secure data transmission. They do this through encryption and certificates. Without HTTPS or FTPS, unauthorized users might be able to capture or modify data, use IP spoofing to attack servers, access unauthorized services, or capture passwords. If you must pass passwords, make sure the back-end application has minimal privileges.

A typical use for an FTP or FTPS port is to get a directory listing, change to the directory that contains the service you want to invoke, put a file that contains input to the service, and run the service. The server returns the output from the service to the directory in which the service resides. Use an e-mail port to receive requests through an e-mail server, such as POP3 or IMAP.

You can define as many ports as you want on each Integration Server instance. The default server instance has an HTTP port at 5555.

Note: The default server instance also defines a diagnostic port at 9999. The diagnostic port uses the HTTP protocol and provides you access to the Integration Server when it is unresponsive. For more information about the diagnostic port, see Diagnosing the Integration Server.
Figure 1. The Server Listens for Requests on Ports that You Specify
The following figure shows the ports on server that listens the requests

There may be times when you want to use the standard port numbers used by web servers: port 80 for HTTP requests and port 443 for HTTPS requests. If your Integration Server runs on a Windows system, this is not a problem. However, if your Integration Server runs on a UNIX system, using a port number below 1024 requires that the server run as "root." For security reasons, Software AG discourages this practice. Instead, run your Integration Server using an unprivileged user ID on a high number port (for example 1024 or above) and use the port remapping capabilities present in most firewalls to move requests to the higher numbered ports.

Services

Client requests involve executing one or more services. The server maintains successfully loaded services as runnable objects within the server's program space.

When you initialize the server, the server loads the services that are contained in enabled packages into memory. When you or another administrator enable a disabled package, the server loads services that are in that package.

Figure 2. Services Execute within the Integration Server's Virtual Machine
The following figure shows that the services execute within Integration Server's virtual machine

When a client invokes a service, that service runs as a thread within the Integration Server program. Depending on what function the service is to accomplish, it can also create additional threads to perform tasks simultaneously.

Retrieving Data for Services

Tasks that services perform often include retrieving data from data sources. The server can retrieve data (for example, XML and HTML data) from local data sources or by issuing HTTP, HTTPS, FTP, FTPS, e-mail, or file polling requests to resources such as web servers and JDBC-enabled databases.

There are a number of methods you can use to send files from a client to the Integration Server. The Integration Server provides the following automated mechanisms:

  • Post a file to a service via HTTP or HTTPS.
  • FTP a file to a service.
  • Submit a file to a service via a file polling port.

  • E-mail a file to a service as an attachment.

Note: If you use Trading Networks, you can send some files, specifically flat files, directly to Trading Networks. For more information about how Trading Networks processes flat files, see the "Defining and Managing Flat File Document Types" chapter in webMethods Trading Networks Administrator’s Guide .

When a client submits a file to the Integration Server, the server uses the appropriate content handler to parse the contents of the file and pass them to the target service.

For all transmission methods except file polling, the client specifies the service to be executed. For file polling, the server always executes the service associated with the file polling port.

For more information about sending and receiving XML files, see webMethods Service Development Help . For more information about sending and receiving flat files, see the Flat File Schema developer's Guide . Refer to the webMethods Integration Server Built-In Services Reference for information about services you can invoke from the service you write.

When the server uses HTTP or HTTPS to access data from external data sources, you can optionally route the requests through a proxy server.
Figure 3. The Server Gets Data from Local Resources or Resources on the Internet
The following figure shows that the server receives data from local resources or resources from the Internet

How the Server Executes Services

When the Integration Server receives a request from a client, it performs the following actions:

  1. The server authenticates the client.
  2. If a session already exists for the client, the server uses the existing session. If one does not exist, the server creates a session.
  3. The server determines the content-type of the service request so it can prepare data for the requested service.

  4. The server uses the supplied service name to look up the service.

  5. The server determines whether access to the requested service is being controlled based on the port on which the request came in. If there is no restriction, the server continues with the execution of the service.
  6. The server checks whether the requested HTTP method is allowed for the service. If it is not, the server sends an back an error message, else the server continues with the execution of the service.
  7. The server looks up the Access Control List (ACL) for the service and determines whether the client is to be granted access to the service. If the ACL indicates that the client is allowed to access the service, the server continues with the execution of the service.
  8. If auditing is enabled, the server adds an entry to the Audit Log to mark the start of the request.
  9. The server starts gathering service statistics for the service.

  10. The server checks to see if the results for this service are in the service-results cache. If service results are cached and the inputs for the cached results match the inputs for this request, the server returns the cached results. If matching results are not cached, the server invokes the service. If the service is a flow service, which can consist of several services, it invokes each service in the flow.

    Note: For each service in a flow, the server performs steps 6 through 11.
  11. The server ends the gathering of server statistics for the service.

  12. If auditing is enabled, the server adds an entry to the Audit Log to mark the end of the request.

  13. The server encodes the service results as specified by the content type.
  14. The server returns the results to the client.

Integration Server Security

Integration Server’s security mechanisms prevent its unauthorized administration, prevent data from being intercepted during transmission, and protect Integration Server services from unauthorized access. You can configure Integration Server to:

  • Use an Enterprise Gateway Server to intercept requests from external clients before passing the requests to your Integration Server. This allows you to isolate Integration Server behind an internal firewall.
  • Require clients to present valid credentials (i.e., user name and password or a client certificate) to authenticate a connection.
  • Authorize access to individual services by user groups, through use of Access Control Lists (ACLs) that you associate with a service. For the greatest security, associate all services with an ACL.
  • Provide transport-level security through Secure Sockets Layer (SSL), and message-level security for web services through WS-Security.
  • Digitally sign documents and verify digital signatures.
  • Control access to services based on the port through which a service request is received.
  • Restrict who can access Integration Server Administrator, and who can use Software AG Designer to connect to the Integration Server.
  • Require clients to present valid user names (with passwords) that have Administrator privileges before allowing access to the Integration Server Administrator functions.
  • Simplify security administration by storing Integration Server SSL certificates and private keys in industry-standard keystore files.
  • Allow different client certificates to be used for different connections.

Integration Server security also depends on the security of its underlying operating system. Make sure you do the following:

  • Follow all vendor recommendations for secure configuration.
  • Remove unnecessary network services that may contain security flaws, such as telnet.
  • Regularly check for and install updates and patches from the operating system vendor that might affect security.

See your operating system’s documentation for instructions on accomplishing these tasks.

For information about security auditing, refer to Security Audit Logging .

Integration Server Logging

Logging for the platform provides important data you need to monitor platform activity and correct problems. Integration Server maintains this logging data. For complete information and instructions about working with logging data, see the webMethods Audit Logging Guide , Setting Up the Server Log, and Setting Up Universal Messaging Client Logging.

Logging, Data Protection, and Privacy

Integration Server includes personally identifiable information (PII) such as user names, email addresses, and client IP addresses in the logs. Integration Server includes PII in logs for purposes of auditing, monitoring activity with the server, and diagnosing and correcting problems. The length of time that Integration Server stores log data depends on the log:

Log Data duration
Server log Data remains in the server log for the duration of the existence of the log file which depends on the watt.server.serverlogFilesToKeep server configuration parameter. This parameter limits the number of server log files that Integration Server maintains on the file system.file. When Integration Server reaches the limit for the number of server log files, Integration Server deletes the oldest archived server log file each time Integration Server rotates the server log.

For more information about watt.server.serverlogFilesToKeep, see Limiting the Number of Server Log Files Kept by Integration Server.

For information about removing data from the Integration Server server log, see Removing Personal Data from Log Files.

File-based audit log Data remains in the log for the duration of the log file existence which depends on the value of watt.server.audit.logFilesToKeep server configuration parameter. This parameter limits the number of audit log files that Integration Server maintains on the file system for each logger. When the number of log files for an audit logger reaches the established limit, Integration Server deletes the oldest audit log file.

For more information about watt.server.audit.logFilesToKeep, see Server Configuration Parameters.

For information about removing data from an Integration Server audit log, see Removing Personal Data from Log Files.

Audit log that writes to a database Data remains in the database table for the log in the ISCoreAudit database until it is removed.

For information about removing data from an Integration Server audit log, see Removing Personal Data from Log Files.

Configuration variables log The length of time that data remains in the configuration variables log depends on whether the log is for an on-premises Microservices Runtime or a Microservices Runtime running in a Docker container. The configuration variables log is overwritten at startup of an on-premises Microservices Runtime. The configuration variable log for a Microservices Runtime running in a Docker container is destroyed when the container is destroyed.

For information about removing data from a configuration variables log, see Removing Personally Identifiable Information from the Configuration Variables Log.

Wrapper log Data remains in the wrapper log for the duration of the log file existence which depends on the value of the wrapper.logfile.maxfiles property for the Java Service Wrapper. For the wrapper.conf file delivered with Integration Server, this property is set to 5. For more information about this property, see Logging Properties.

For information about removing data from the wrapper log, see Removing Personally Identifiable Information Logged by Axis2, Kerberos, SAML, and other Third Party Libraries.

SSL session log Data remains in the inboundSSLSessions.log until it is removed. The watt.net.ssl.server.sessionlog.maxFileSize server configuration parameter limits the size of the inboundSSLSessions.log file. When the file reaches the maximum size limit, Integration Server renames the file to sslsession_<DATE(YYYYMMDD)>_TIME(HHMMSS).log and creates a new inboundSSLSessions.log file.

For more information about watt.net.ssl.server.sessionlog.maxFileSize, see Server Configuration Parameters.

For information about removing data from the inbound SSL session log, see Removing Personally Identifiable Information from the SSL Session Log.

Integration Server Caching

Caching is an optimization feature that can improve the performance of services by maintaining frequently used data in memory. Caching can significantly improve response time of services that retrieve information from high-traffic web servers and databases.

Integration Server uses the caching capabilities of Terracotta Ehcache to provide:

  • Service results caching. When you enable services to cache results, Integration Server saves the service invocation results in the cache for a specified period of time. While the results are in cache, rather than re-invoking the service, Integration Server can quickly retrieve the service results for subsequent clients' requests for the service. For more information about service caching, see Caching Service Results.
  • Data caching. With Terracotta Ehcache, you can define individual caches in which services can cache data. Services that want to cache data do so using the caching services provided in the pub.cache folder. Terracotta Ehcache enables you to cache virtually any kind of object. Additionally, it provides advanced features such as off-heap caching and distributed caching. For more information about using Terracotta Ehcache, see Configuring Terracotta Ehcache on Integration Server.

About Integration Server Fixes

Software AG delivers fixes for Integration Server via the Software AG Update Manager. In addition to including resolutions to product defects, a fix may also include enhancements to existing functionality and features. Any of these items can result in new or changed built-in services, APIs, or configuration parameters. Review the fix contents carefully before applying the fix.

The fix readme file serves as the documentation for the functionality delivered in a fix. The released product documentation is not typically updated for fix functionality. In the event that the released product documentation is updated for functionality delivered in a fix, the refreshed product documentation will include a note identifying the fix in which the functionality was made available.