Manage the Copilot server

The Copilot server provides a number of functions that support the following services: the Transfer CFT UI, the former Transfer CFT UI (Copilot), REST API services, web services, multi-host/multi-node architectures, and Central Governance.

This page describes how to start/stop and check the status of the Copilot server.

Start / stop Copilot

To start the Copilot server, run the command:

copstart

To stop the Copilot server, run the command:

copstop
Note For details on starting in your specific operating system, refer to the corresponding Transfer CFT 3.3.2 Installation Guide.

Check Copilot status

To check the Copilot status, enter:

copstatus

The copstatus return code is 0 when Copilot is running, and 1 when Copilot is stopped.

Additional copstatus commands include:

copstatus [-p] [-v] [-h|--help]

-p print copsmng pid if copilot is started

-v print status message

-h|--help copstatus help

Windows menus

You can also use the Windows Start menu to start Axway software. From the Start menu, select Programs (or All Programs), Axway Software and then the product.

For example, to start the Copilot server click Start > All Programs > Axway Software > Transfer CFT > Start Transfer CFT UI Server.

Operating system specific tasks

z/OS

Start

COPRUN is an example of a JCL statement that starts the Transfer CFT Copilot server. The server can be started as a Start Task. The Transfer CFT Copilot server STEPLIB, and then JOBLIB should be defined as an APF. If it is not defined as an APF, no RACF check can be performed. This results in no log-on check being available and all requests are done with the user associated with the server JOB.

When the copilot.misc.CreateProcessAsUser variable is set, STEPLIB or JOBLIB can be non-APF. Only a Central Governance/PassPort user can sign on to Copilot user interface.

Note When the ‘cft.mvs.copilot.check_apf’ uconf variable is set to ‘Yes’, CFTCOPL must be APF authorized to start.

LOG message: +CFTI42E Copilot must be APF-authorized.

Note CFTCOPL must be APF authorized to start if the UCONF cft.mvs.copilot.check_apf variable is set to Yes. Otherwise, the Transfer CFT log displays CFTI42E Copilot must be APF-authorized.

Stop

COPSTOP is an example of the JCL stop statement for the Transfer CFT Copilot server. You can also stop the Copilot server using the operator command pause (/P jobname) for the server-associated task.

IBM i

Start

Menu

  1. Access the Transfer CFT Main Menu.
  2. In the Main Menu enter the command cft and press Enter to open the Transfer CFT menu.
  3. Enter 1 to access Common CFT commands.
  4. Select option 1 Start Copilot. The Copilot server menu is displayed.

Command

Execute: COPSTART

Stop

Menu

  1. Access the Transfer CFT Main Menu.
  2. In the Main Menu enter the command cft and press Enter to open the Transfer CFT menu.
  3. Enter 1 to access Common CFT commands.
  4. Select option 2 Stop Copilot.
    Only the server waiting for a connection is stopped. Other servers that users have logged onto are shut down when the user logs off, or after a network timeout.

Command

Execute: COPSTOP

Copilot server configuration

General Copilot user interface parameters

The following table lists the UCONF identifiers and the default values for the Transfer CFT Copilot (UI).

ID Default Description

copilot.general.serverport

1766 

Copilot (UI) server listening port.

copilot.general.serverhost  

0.0.0.0 

TCP Copilot (UI) server address, where 0.0.0.0 indicates that you want Copilot to listen on all network interfaces if your machine has more than one.

UNIX

Refer to the UCONF parameters table for information on copilot.*.unix parameters.

Alias management

You can access customized file system directories via the Transfer CFT user interface HTTP server using aliases.

To add a new alias, access the Unified Configuration uconf and configure the following:

ID Description
copilot.http.aliases List of enabled alias-id
copilot.http.aliases.(alias-id) alias Name of the alias
copilot.http.aliases.(alias-id).path Path that replaces the alias in the URL

Security for Copilot UI

Parameter Description
copilot.http.onlyssl Enter Yes to restrict the access of the Transfer CFT GUI with https.

View available drives

To view available drives from the Edit a file icon in the graphical user interface, define the following:

Parameter Options Description
copilot.nt.rootdrives @REMOVABLE_DRIVES To view removable drives such as a USB key, CD, and so on.
@LOCAL_DRIVES To view hard drives.
@NET_DRIVES To view network drives.

Client keep-alive

Use this parameter to define the keep-alive interval in seconds for a client session. By default this occurs every 60 seconds.

Parameter Value
copilot.misc.client_keep_alive_delay

Enter an integer for the delay in seconds.

60 = default

0 = no keep-alive

Client timeout

Use this parameter to define the client timeout in minutes. The default value is 30 minutes.

Parameter Value
copilot.misc.ClientTimeout

Enter an integer for the timeout in minutes.

30 = default

0 = no timeout

Web services

Use these parameter to define the Transfer CFT Web Services. See also Setting up Web Services.

Parameter Value Former value
copilot.webservices.wsicomplience (bool) No [WEBSERVICES] WsiComplience
copilot.webservices.upload_directory (dir) $(cft.runtime_dir)/conf/ws_upload NA

REST API server

Use these parameter to configure the REST API server. See also Transfer CFT REST API concepts.

Parameter Type Default Description
copilot.restapi.enable bool No

Enable/disable the REST API service:

  • Yes: enable
  • No: disable
copilot.restapi.serverport int 1768

REST API server port.

copilot.restapi.authentication_method string

system (Windows)

xfbadm (UNIX)

Defines authentication method.
copilot.restapi.nb_workers int 1 Number of activated workers that process the REST API requests.
copilot.restapi.maxclient int 256 Number of client connections handled per REST worker.
copilot.restapi.coms_id string coms

The TCPIP CFTCOM object identifier used by the REST API server to communicate with the Transfer CFT server.

Leave empty to use the COM file instead.

copilot.restapi.catalog.retry_delay int 5
  • The delay between retries in seconds. The Copilot server checks the request status in catalog every retry_delay seconds.
  • The delay between retries in seconds. The Copilot server checks the request status in catalog every retry_delay seconds.
copilot.restapi.catalog.retry_timeout int 30

The default value of the apiTimeout parameter as defined in the request URL.

Available exclusively for POST requests.

Configure Copilot with SSL security

This section describes how to install the certificates that are required to enable:

  • Transfer CFT UI (web browser-based)
  • REST API  
  • HTTPS connections for Copilot

The basic steps are:

  • Install a certificate on the server side
  • Install a certificate on the client side
  • Connect to Copilot using an SSL connection

Operating system specific limitations

  • For z/OS, certificates can be USS or sequential files.
  • For IBM i (OS/400), certificates must be native files if you have enabled the REST API interface. If only Copilot is enabled, IFS files are supported (as in the previous version).

Install a certificate on the server side

When using Central Governance

The Copilot server uses the certificate that was created by Central Governance during the product registration. This certificate is stored in Transfer CFT PKI database and the certificate id is the value of the UCONF cft.instance_id parameter. This means that there is no action required to install a certificate.

However, to override the default behavior use the procedure described below in When using Transfer CFT without governance.

When using Transfer CFT without governance

The following tables describe the UCONF parameters that determine the certificates used by the Copilot server to authenticate itself.

You can use the following certificate and private key formats, where the format of the certificate may differ from that of the key.

The certificate type is dictated by the file name extension (e.g. p12, pkcs12, dem, pem). For native files in a z/OS or IBM i environment, if the format cannot be determined (the file suffix used as the extension), Transfer CFT derives the value from these uconf settings:

  • copilot.ssl.sslkeyfile=<not set> and copilot.ssl.sslcertpassword=<set>, then the format is PKCS12
  • copilot.ssl.sslkeyfile= <set> and copilot.ssl.sslcertpassword=<not set>, then the format is PEM
Supported format Type Extension
Certificate PKCS#12 p12, pfx, pkcs12
PEM pem
DER der
Private key PEM pem
DER der
PKCS#8 key, pem

How to define a PKCS#12 certificate

This example uses a single PKCS#12 certificate where you only require the file name and password.

Parameter

Value

copilot.ssl.SslCertFile

conf/pki/<my_certificate>.p12

copilot.ssl.SslCertPassword

Certificate password

copilot.ssl.SslKeyFile

Not used

copilot.ssl.SslKeyPassword

Not used

How to define a DER or PEM certificate

This example uses a DER(or PEM) certificate with the private key in a separate DER file, where you define the key as well as the certificate.

Parameter

Value

copilot.ssl.SslCertFile

conf/pki /<my_certificate>.der or .pem

copilot.ssl.SslCertPassword

Not used

copilot.ssl.SslKeyFile

conf/pki /<my_key>.der or .pem

copilot.ssl.SslKeyPassword

Key password, which is mandatory if the key file is encrypted PKCS#8

Additional HTTPS parameters

There are two additional UCONF parameters to use for HTTPS connections:

Parameter

Value

copilot.http.onlyssl

  • No: Default value.
  • Yes: Restricts access to the Copilot server to HTTPS secured connections only.

copilot.ssl.SslCipherSuites

 

A comma separated list of cipher suites accepted by the Copilot server, for example: “47, 10, 9, 2”.

See the Supported cipher suites for details.

Install a certificate on the client side

Windows

On Windows, there are two ways to install a certificate on the client side - using a Windows certificate or the Java keystore.

UNIX

On Linux, using the Java keystore is the only option.

Install a certificate in the Windows keystore

  1. In Windows Explorer, navigate to the certificate <my_root_certificate>.der and right-click (for example, at <CFTDIRRUNTIME>/conf/pki/<my_root_certificate>.der).
  2. Select the Install certificate option.
  3. Follow the screen instructions. Windows automatically imports the certificate to its keystore in the Intermediate certificate authorities folder.

Alternative method

  1. In Internet Explorer, select Tools > Internet Options.
  2. In the Content tab select the Certificate button.
  3. Select Import, which starts the Certificate Import Wizard.
  4. Click Next, and Browse to the <my_root_certificate>.der.
  5. Follow the screen instructions. Windows imports the certificate to its keystore.

Install a certificate in the Java keystore

The Java keystore is a file located at ~/jre/lib/security/cacerts. The default password for this keystore is “changeit”.

Use the keytool command as follows to import the <my_root_certificate>.der certificate into the Java keystore:

keytool importcert

   -trustcacerts

   -alias AXWMFTCA

   -file <my_root_certificate>.der

   -storepass changeit-keystore <keystore>

Related Links