C.1 Connection configuration file

In the connection configuration file, you set the HTTP-connection-related information that is required to call a web API.

If you include security information (such as a password) in this file, you do so on your own responsibility.

The following table describes the specifications of the connection configuration file.

Table C‒1: Specifications of the connection configuration file
No.	Definition	Description
1	Permission	The job execution user requires read permission for the file.
2	Character encoding	The file must be written with the same character encoding that is used on the agent host on which HTTP connection jobs are executed.
3	Maximum size	1,024 bytes

A model file for the connection configuration file is provided. You can create a connection configuration file by editing a copy of the model file. You can also create a new connection configuration file by following the format shown below.

The location of the model connection configuration file is as follows.

In Windows:: installation-folder-for-JP1/AJS3-Manager-or-JP1/AJS3-Agent\conf\ajshttpreq_network.conf.model
In Linux:: /etc/opt/jp1ajs2/conf/ajshttpreq_network.conf.model

After creating the connection configuration file, you can place it at any location on the agent host on which HTTP connection jobs are to be executed.

Organization of this subsection

(1) Format
(2) Setting items
(3) Format of the model file
(4) Cautionary notes

(1) Format

The format of the connection configuration file is as follows:

URL=connection-destination-URL
HttpVer=HTTP-version
ConnectTimeout=connection-timeout-value
Timeout=maximum-processing-time-of-the-entire-HTTP-connection-job
MaximumReceivedDataSize=maximum-size-of-receive-data
ClientBindAddrIP=IP-address-of-the-client-to-be-bound
Header=additional-header
Authorization=whether-to-use-Basic-Authentication-on-the-web-server
UserName=user-name-used-for-Basic-Authentication-on-the-web-server
UserPass=password-used-for-Basic-Authentication-on-the-web-server
Proxy=proxy-server-name
ProxyAuthorization=whether-to-use-proxy-server-authentication
ProxyUserName=user-name-used-for-proxy-server-authentication
ProxyUserPass=password-used-for-proxy-server-authentication
CAFile=certificate-file-name
CrlFile=certificate-revocation-list-file-name

Lines beginning with a hash mark (#) are treated as comment lines. Lines on which only single-byte spaces and/or tabs appear before a hash mark (#) are also treated as comment lines.

To Page Top

(2) Setting items

The entries in the connection configuration file are described below. In the file, specify each entry on a separate line.

(a) URL=<connection-destination-URL>

Specify the connection destination URL, using a character string that is 2,083 or fewer bytes long. The URL must begin with http:// or https://. You can use only single-byte characters.

When specifying the connection-destination-URL, you cannot include URL parameters. To include URL parameters in the connection-destination-URL, specify the URL parameters in the transmission information file.

To use a port number that is not the default port number, include the port number in the URL. The default port number is as follows:

For http: 80
For https: 443

In the case of https, you must specify CAFile=name-of-the-certificate-file.

This entry cannot be omitted.

(b) HttpVer=<HTTP-version>

Specify either of the following values as the HTTP version:

1.0: Uses HTTP 1.0 to send a request.
1.1: Uses HTTP 1.1 to send a request.

This entry can be omitted. If omitted, 1.1 is assumed.

(c) ConnectTimeout=<connection-timeout-value>

Specify in seconds the maximum wait time before a connection to the destination host can be established. You can specify a value from 1 to 600.

If a connection to the destination host is not established within the specified time, the HTTP connection job terminates abnormally.

This entry can be omitted. If omitted, 10 is assumed.

Cautionary note: Depending on the OS settings on the host on which the HTTP connection job is executed and the network settings in the system, a timeout might occur before the specified time expires, causing the job to terminate abnormally. For details about the OS settings, see the documentation for the OS.

(d) Timeout=<maximum-processing-time-of-the-entire-HTTP-connection-job>

Specify in seconds the maximum processing time of the entire HTTP connection job. You can specify a value from 1 to 86,400.

If the processing does not finish within the specified time, the HTTP connection job terminates abnormally.

This entry can be omitted. If omitted, 600 is assumed.

(e) MaximumReceivedDataSize=<maximum-size-of-receive-data>

Specify in megabytes the maximum size of data that can be received from a web API. You can specify a value from 1 to 1,024.

The value specified for this entry is compared with the value of the Content-Length HTTP header of the received data. If the Content-Length value is larger, data reception stops and the HTTP connection job terminates abnormally.

If the data being received does not contain the Content-Length HTTP header, the size of the received data is checked in real time. When the size of received data in the HTTP body reaches the specified value, data reception stops and the HTTP connection job terminates abnormally.

This entry can be omitted. If omitted, 500 is assumed.

(f) ClientBindAddrIP=<IP-address-of-the-client-to-be-bound>

To bind a client, specify the IP address of the client by using a character string that is 39 or fewer bytes long.

You can specify either an IPv4 address or an IPv6 address.

This entry can be omitted. If omitted, no client is bound.

Cautionary note: You must bind a client if you want to use either a specific IP address for passing through the firewall or a specific LAN.

(g) Header=<additional-header>

To add a header to the HTTP header in a request, specify the header by using a character string that is 1,024 or fewer bytes long.

You can specify this entry on multiple lines to add multiple headers. If the settings of additional headers specified in Header=additional-header entries are the same as the header settings specified by the HTTP connection job, the settings specified by the Header=additional-header entries take precedence.

You can specify each Header=additional-header entry in one of the following formats:

Header=header-name:header-value: To add a custom header that has a value, specify the header name and value with an intervening colon (:). For example, to add a header whose name is ABC and whose value is DEF, specify Header=ABC:DEF.
Header=header-name:: To disable a header that is set by the HTTP connection job, specify the header name followed by a colon (:). For example, to disable the ABC header, specify Header=ABC:.
Header=header-name;: To add a custom header that does not have a value, specify the header name followed by a semicolon (;). For example, to add the ABC header that has no value, specify Header=ABC;.

This entry can be omitted. If omitted, no header is added.

Cautionary note: If you disable headers that are set by the HTTP connection job, the job might not be executed normally. Before you disable such headers, fully consider the impact.

(h) Authorization=<whether-to-use-Basic-Authentication-on-the-web-server>

Specify either of the following values to determine whether to use Basic Authentication on the web server:

y: Uses Basic Authentication on the web server.
n: Does not use Basic Authentication on the web server.

If you specify y, the Authorization header is specified as an HTTP header in the request based on the values specified for the following entries: UserName=user-name-used-for-Basic-Authentication-on-the-web-server and UserPass=password-used-for-Basic-Authentication-on-the-web-server. Note that if a Header=additional-header entry is used to specify another Authorization header, the Authorization header specified as an additional header takes effect.

To use an authentication method other than Basic Authentication, you must use a Header=additional-header entry to specify the method.

If y is specified when the connection destination host does not require authentication on a web server, how the system behaves depends on the specifications of the web server for the connection destination.

This entry can be omitted. If omitted, n is assumed.

(i) UserName=<user-name-used-for-Basic-Authentication-on-the-web-server>

If you choose to use Basic Authentication on a web server, specify the user name that is used for authentication by using a character string that is 256 or fewer bytes long. The user name you specify must not include colons (:).

To use Basic Authentication on a web server, this entry cannot be omitted.

(j) UserPass=<password-used-for-Basic-Authentication-on-the-web-server>

If you choose to use Basic Authentication on a web server, specify the password that is used for authentication by using a character string that is 256 or fewer bytes long.

To use Basic Authentication on a web server, this entry cannot be omitted.

(k) Proxy=<proxy-server-name>

To use a proxy server, specify the name of the proxy server by using a character string that is 2,083 or fewer bytes long.

To use Basic Authentication on a proxy server, this entry cannot be omitted.

(l) ProxyAuthorization=<whether-to-use-proxy-server-authentication>

To use a proxy server, specify either of the following values to determine whether to use Basic Authentication on a proxy server:

y: Uses Basic Authentication on a proxy server.
n: Does not use Basic Authentication on a proxy server.

If you specify y, the ProxyAuthorization header is specified as an HTTP header in the request based on the values specified for the following entries: ProxyUserName=user-name-used-for-proxy-server-authentication and ProxyUserPass=password-used-for-proxy-server-authentication. Note that if a Header=additional-header entry is used to specify another ProxyAuthorization header, the ProxyAuthorization header specified as an additional header takes effect.

To use an authentication method other than Basic Authentication, you must use a Header=additional-header entry to specify the method.

If y is specified when the connection destination host does not require authentication on a proxy server, how the system behaves depends on the specifications of the proxy server for the connection destination.

This entry can be omitted. If omitted, n is assumed.

(m) ProxyUserName=<user-name-used-for-proxy-server-authentication>

If you use Basic Authentication on a proxy server, specify the user name that is used for authentication by using a character string that is 256 or fewer bytes long. The user name you specify must not include colons (:).

To use Basic Authentication on a proxy server, this entry cannot be omitted.

(n) ProxyUserPass=<password-used-for-proxy-server-authentication>

If you choose to use Basic Authentication on a proxy server, specify the password that is used for authentication by using a character string that is 256 or fewer bytes long.

To use Basic Authentication on a proxy server, this entry cannot be omitted.

(o) CAFile=<certificate-file-name>

If you specified a character string starting with https:// in URL=connection-destination-URL, specify the file name of the root certificate by using a character string that is 511 or fewer bytes long. The root certificate must be in PEM format. If you specify a root certificate in DER format, the KAVS8062-E message is output and the HTTP connection job terminates abnormally.

If you specified a character string starting with http:// in URL=connection-destination-URL, this entry can be omitted.

(p) CrlFile=<certificate-revocation-list-file-name>

To verify the server certificate, specify the name of the certificate revocation list file by using a character string that is 511 or fewer bytes long. The certificate revocation list file must be in PEM format. If you specify a file in DER format, the KAVS8062-E message is output and the HTTP connection job terminates abnormally.

This entry can be omitted. If omitted, the check of the certificate revocation status will not be performed.

To Page Top

(3) Format of the model file

The format of the model file of the connection configuration file is as follows:

URL=
#HttpVer=1.1
#ConnectTimeout=10
#Timeout=600
#MaximumReceivedDataSize=500
#ClientBindAddrIP=
#Header=
#Authorization=n
#UserName=
#UserPass=
#Proxy=
#ProxyAuthorization=n
#ProxyUserName=
#ProxyUserPass=
#CAFile=
#CrlFile=

Omissible entries are commented out. To specify those entries explicitly with desired values, delete the hash marks (#) and specify the desired values.

To Page Top

(4) Cautionary notes

The following lines are ignored:
- Blank lines
- Lines containing only single-byte spaces or tabs
Single-byte spaces or tabs at the beginning and end of an entry are deleted.
The only entry that can be specified on multiple lines is Header=additional-header. If an entry other than Header=additional-header is specified on multiple lines, only the last specified one takes effect.
If the connection configuration file contains entries other than the entries indicated in this appendix, the HTTP connection job terminates abnormally.
If you specify only an entry name without specifying a value, the HTTP connection job terminates abnormally.

To Page Top