CloudBees Flow Installed Tools

addTrustedServer crt

Add a server CA certificate to the agent’s keystore.

getCRL

Retrieve the contents of the current certificate revocation list.

initAgent [ --local | --remote ] [ options ]

Initialize the agent keystore with a new public/private key pair. Generates the agent certificate signing request. If run on the server host, the certificate will automatically be signed by the server CA, and the CA certificate and the signed agent certificate are installed in the agent’s keystore. If run on a non-server host, the signing request is left in the agent directory. If CA Cert is provided, the CA certificate is installed in the agent’s keystore.

--local

Use the local server CA to sign the agent certificate.

--remote

Connect to a remote CloudBees Flow server to sign the agent certificate.

--force

Replace any existing keystore.

--cname name

Use the specified name as the common name (CN) in the agent certificate subject. This is normally the fully qualified domain name used by clients to connect to the agent.

--altNames entries

Use the specified list of entries (comma or space separated) as the subjectAlternateNames list in the agent certificate. Simple names are interpreted as dns entries. Entries may begin with "dns:" or "ip:" to indicate the type (for example, ` "ip:192.168.0.1"` or "dns:myHost" ). If no entries are specified, then reverse DNS is used to look up the registered names of the host’s IP addresses.

initCA

Initialize the server CA. Creates a new CA key and certificate.

initServer [ options ]

Initialize the server keystore. Creates and signs the server certificate. Installs the CA certificate and the signed server certificate into the server’s keystore.

--force

Replace any existing keystore.

--cname name

Use the specified name as the common name (CN) in the server certificate subject. This is normally the fully qualified domain name used by clients to connect to the server.

--altNames entries

Use the specified list of entries (comma or space separated) as the subjectAlternateNames list in the server certificate. Simple names are interpreted as dns entries. Entries may begin with "dns:" or "ip:" to indicate the type (for example, "ip:192.168.0.1" or "dns:myHost" ). If no entries are specified, then reverse DNS is used to look up the registered names of the host’s IP addresses.

list [ --agent | --server | --index [ --verbose ]

Display certificate information for agent and/or server keystores or the CA certificate index. If no options are specified, both the agent and server keystores are listed.

--agent

List the contents of the agent keystore.

--server

List the contents of the server keystore.

--index

List the contents of the CA issued certificates index.

--verbose

Display additional details.

refreshCRL

Refresh the certificate revocation list from the CloudBees Flow server.

revoke index

Revoke a previously issued certificate by index.

signCertificate csr crt

Sign the certificate signing request provided in file csr and write the signed result to the file crt. The request is rejected by the CA if there is a matching certificate already in the CA database.

updateAgentCertificate crt

Install a previously signed certificate crt into the agent’s keystore.

Address of the CloudBees Flow server. Defaults to the value of the COMMANDER_SERVER environment variable. If that does not exist,it defaults to localhost.

HTTPS listener port on the server. Defaults to 8443.

Print the Help message.

Print the version message.

--agentAcceptQueueSize=max

The maximum number of pending connections the agent will queue up.

--agentArtifactCache=path

The directory containing cached artifactVersions.

--agentCaFile=path

A single file containing multiple CA certificates.

--agentCaPath=path

A directory containing a file for every CA, where each file’s name is the CA subject name hash value.

--agentCertFile=path

Location of the certificate file used by the agent to support SSL connections from the server.

--agentCrlFile=relativepath

Relative path of the file containing the agent’s certificate revocation list for SSL.

--agentDomainName=domain

The domain name that the agent uses for fully-qualified names.

--agentDuplicateDetectionListSize=size

The size of the list of recently seen requests used in duplicate request detection.

--agentEnableProxySettings=<1|0>

Enable (1) or disable (0) the proxy server configuration. If enabling for the first time, --agentProxyHost and --agentProxyPort must be specified.

--agentIdleConnectionTimeout=milliseconds

Idle connection timeout, in milliseconds.

--agentIdleOutboundConnectionTimeout=seconds

Idle time after which an outbound connection is closed, in seconds.

--agentIdlePostRunnerTimeout=seconds

Idle time after which a PostRunner thread is terminated, in seconds.

--agentIdleServerRequestWorkerTimeout=seconds

Idle time after which a ServerRequestWorker thread is terminated, in seconds

--agentIdleWorkerTimeout=seconds

Idle time after which a Worker thread is terminated, in seconds.

--agentInitMemory=percent

Initial java heap size as a percentage of the total system memory.

--agentInitMemoryMB=size

Initial java heap size in MB.

--agentKeyFile=path

Location of the key file used by the agent to support SSL connections from the server.

--agentKeystore=path

Location of the keystore file used by the agent to support SSL connections from the server.

--agentKeystorePassword=password

Password used to access the agent’s keystore.

--agentLoadProfile=<true|yes|1|false|no|0>

Enable (1) or disable (0) loading the impersonated user’s profile for impersonation steps if on Windows.

--agentLocalPort=port

Port used by the Commander agent for http communication on the localhost network interface.

--agentLogFile=path

Path where the C++ agent log file should be written.

--agentLogLevel=<TRACE|DEBUG|INFO|WARN|ERROR>

Logging level used by the C++ portion of the agent.

--agentLogMaxFiles=max

Maximum number of log files the C++ agent will accrue.

--agentLogMaxSize=max

Maximum size of each log file from the C++ agent. The value may be suffixed with a unit (MB, KB, B). Without a unit, the value is interpreted as bytes.

--agentMaxConnections=max

Maximum number of network connections for the agent.

--agentMaxConnectionsPerRoute=max

Maximum number of network connections per route for the agent.

--agentMaxHttpThreads=max

Maximum number of threads for handling inbound requests.

--agentMaxLoggedMessageLength=max

Maximum message length, used when logging requests/ responses to/from the CloudBees Flow server.

--agentMaxMemory=percent

Maximum java heap size as a percentage of the total system memory.

--agentMaxMemoryMB=size

Maximum java heap size in MB.

--agentNoProxyHosts=hosts

Comma delimited list of hosts that should be reached directly, bypassing the proxy server.

--agentOutboundConnectTimeout=milliseconds

Timeout for the agent establishing outbound connections, in milliseconds.

--agentOutboundRequestInitialRetryInterval=seconds

Initial delay between retries for sending outbound requests to a server, in seconds.

--agentOutboundRequestMaxRetryInterval=seconds

Maximum delay between retries for sending outbound requests to a server, in seconds.

--agentOutboundRequestTimeout=hours

Timeout after which the agent gives up trying to send a request to a server, in hours.

--agentPluginsDirectory=path

The path used by the agent to get to the plugins directory of the CloudBees Flow server where its resource definition lies.

--agentPort=port

Port used by the Commander agent for https communication on any network interface.

--agentProto=<http|https>

Protocol used internally by the agent.

--agentProtocol=<http|https>

Protocol used by the agent.

--agentProxyHost=host

The IP address of the proxy server.

--agentProxyPort=port

The port of the proxy server.

--agentServerConnectTimeout=seconds

Socket connection timeout for outbound requests to a server, in seconds.

--agentServerReadTimeout=seconds

Socket read timeout for responses from a server, in seconds.

--agentServerSessionsFile=relativepath

Relative path to the persisted server sessions file.

--agentTLSEnabledProtocol < protocols >

Comma-delimited list of SSL/TLS protocols that will be allowed for agent connections using HTTPS. The possible values are any combination of TLSv1, TLSv1.1, TLSv1.2, and SSLv2Hello.

The default security configurations are as follows:

We recommend removing the SSL 2.0 Client Hello or SSLv2Hello protocol from your security configurations for all components. When you do this, you would also need to upgrade older agents to the latest version to avoid security risks. You would need to upgrade agents if you are using the following agent versions:

--agentUnixShellPattern=pattern

Windows-only: ordinarily, the agent creates script-files with CRLF line termination. But some shells on Windows require script files to be LF line-terminated, like Unix. This option sets a regular expression pattern for such shells. Defaults to a pattern that matches sh and bash, which in modern versions of Cygwin require LF-terminated script files.

--agentVerifyPeer=<true|yes|1|false|no|0>

Enable (1) or disable (0) verifying the certificate presented by the CloudBees Flow server when it connects.

--agentWrapperConsoleFormat=format

Format of output for the agent wrapper console.

--agentWrapperEcwrapperWriteMaxAttempts=max

Workspace write maximum attempts count

--agentWrapperEcwrapperWriteRetryInterval=milliseconds

Workspace write interval between two attempts, in milliseconds.

--agentWrapperJavaAdditional=nnnnn=value

Set a custom line of the form wrapper.java.additional.nnnnn=value in the agent’s wrapper.conf file. nnnnn must be an integer >= 10000.

--agentWrapperJavaClasspath=n=path

The Java classpath. n must be an integer >= 1.

--agentWrapperJavaLibraryPath=n=path

The Java Library Path (location of Wrapper.DLL or libwrapper.so). n must be an integer >= 1.

--agentWrapperLogfile=path

Log file to use for agent wrapper output logging.

--agentWrapperLogfileFormat=format

Format of output for the agent wrapper log file.

--agentWrapperLogfileLoglevel=loglevel

Log Level for agent wrapper log file output.

--agentWrapperLogfileMaxsize=size

Maximum size that the log file will be allowed to grow to before the log is rolled. Size is specified in bytes, kilobytes with a 'k' suffix, or megabytes with an 'm' suffix.

--agentWrapperLogfileMaxfiles=max

Maximum number of rolled log files which will be allowed before old files are deleted.

--agentWrapperNtserviceDependency=n=service

NT service dependencies. Add dependencies as needed starting from 1. n must be an integer >= 1.

--agentWrapperNtserviceStarttype=<AUTO_START|DEMAND_START>

Mode in which the NT service is installed.

--agentWrapperNtserviceInteractive=<true|false>

Whether to allow the NT service to interact with the desktop.

--agentWrapperPingInterval=seconds

Java virtual machine-wrapper heartbeat interval, in seconds.

--agentWrapperPingTimeout=seconds

Java virtual machine-wrapper heartbeat timeout, in seconds.

--agentWrapperRequestThreadDumpOnFailedJvmExit=<true|false>

Whether to try to get a thread dump if the Java virtual machine doesn’t exit cleanly.

--agentWrapperShutdownTimeout=seconds

The wrapper’s shutdown timeout, in seconds.

--agentWrapperStartupTimeout=seconds

The wrapper’s startup timeout, in seconds.

--agentWrapperSuccessfulInvocationTime=seconds

The amount of time the agent has to be up before the wrapper considers it a 'successful' invocation. If there are 5 or more consecutive failed invocations, the wrapper will no longer start up the agent.

--agentWrapperSyslogLoglevel=loglevel

Log Level for sys/event agent wrapper log output.

--skipServiceRestart

Disable the attempt to restart the web server. The CloudBees Flow web server can only be started with sudo access. Therefore, you must use sudo to restart it manually afterward or use the --skipServiceRestart option to disable the restart attempt.

--webHostName=host

The host name of the current machine in the form that users will typically use in their browser to access the web server.

--webHttpPort=port

The HTTP port of the web server.

--webHttpsPort=port

The HTTPS port of the web server.

--webTargetHostName=host

The host name of the CloudBees Flow server to which the web server points.

This argument modifies the CloudBees Flow web server configuration and therefore also attempts to restart the CloudBees Flow web server. If you used the ecconfigure command without sudo as recommended, the commanderApache service will not start and produces an error. Therefore, you must restart it manually afterward using sudo. You can also use the --skipServiceRestart argument to avoid the ecconfigure command’s restart attempt and the error message.

--webTargetHttpPort=port

The HTTP port of the CloudBees Flow server to which the web server points.

--webTargetHttpsPort=port

The HTTPS port of the CloudBees Flow server to which the web server points.

--webTimeZone=timezone

The Olson TimeZone format (example: America/Los Angeles) for the php web server.

--webPluginsDirectory=path

The path used by the web server to get to the plugins directory of the CloudBees Flow server to which it points.

--webProxyUrl=url

The IP address and port of the proxy server in the following format. https://<IP_ADDRESS_PROXY>:<PROXY_PORT>

--webServicePrincipalName=name

The Kerberos Service Principal Name that will be used to authorize users. This command changes the KrbServiceName HTTP setting in the DATA_DIR/apache/conf/extra/auth-kerberos.conf file.

--webNoProxyHosts=hosts

Comma delimited list of hosts that should be reached directly, bypassing the proxy server.

--webEnableKerberosConstrainedDelegation=<true|false>

Enable ( true ) or disable ( false ) support for constrained delegation authorization when using the Kerberos SSO protocol. This parameter manages the KrbConstrainedDelegation setting in DATA_DIR/apache/conf/extra/auth-kerberos.conf.

--webEnableKrb5Trace=<1|0>

Enable (1) or disable (0) additional Kerberos protocol logging for the web server. This parameter manages the webEnableKrb5Trace setting in DATA_DIR/apache/conf/extra/auth-kerberos.conf.

--webEnableProxySettings=<1|0>

Enable (1) or disable (0) the proxy server configuration. If enabling for the first time, --webProxyUrl must be specified.

--webEnableSsoKerberos =<true|false>

Enable ( true ) or disable ( false ) authentication using the Kerberos SSO protocol. This command changes the $config["ssoEnabledKerberos"] variable in the INSTALL_DIR/apache/htdocs/commander/config.php file.

--webDisableHttpsRedirection=<1|0>

Disable (1) or enable (0) HTTP → HTTPS web redirection by the web server.

--webCsrfProtection=<true|false>

Enable (true) or disable (false) Cross-Site Request Forgery protection on the web server.

--serverAcceptQueueSize=max

The maximum number of pending connections the CloudBees Flow server will queue up.

--serverBatchDbRequestsOverride=<1|0|auto>

Enable (1), disable (0) or let the server decide (auto) for using db request batching.

--serverBindIp=<ip or hostname>

The IP address or host name the CloudBees Flow server listen to.

--serverCertFile=relativepath

Relative path of the certificate file used by the CloudBees Flow server to support SSL connections.

--serverChangeTrackingHardMaxRecords=number

The maximum number of records for change tracking

--serverCommanderPort=port

The HTTP port of the server.

--serverCommanderHttpsPort=port

The HTTPS port of the server.

--serverCriticalServicesMonitoringEnabled=<true|false>

Enable (true) or disable (false) monitoring for the critical services.

--serverCriticalServicesMonitoringFrequency=seconds

The interval between the critical services checks and the disk space checks, seconds.

--serverCrlFile=relativepath

Relative path of the file containing the CloudBees Flow server’s certificate revocation list for SSL.

--serverDatabaseName=name

The name of the database the CloudBees Flow server uses for its operation.

--serverDatabaseUsername=name

The user name for the database the CloudBees Flow server uses for its operation.

--serverFileTransferPort=port

The file transfer port of the server.

--serverForceEnableAdmin=<1|0>

Set to '1' or '0' to override the current value of the 'enableAdminUser' CloudBees Flow server setting.

--serverName=host

The name the CloudBees Flow server, usually its fully-qualified domain name, or for a cluster the fully-qualified domain name of the load balancer.

--serverHttpPort=port

The HTTP port of the server, default value 8000.

--serverHttpsPort=port

The HTTPS port of the server, default value 8443.

--serverIgnoreServerMismatch=<1|0>

Enable (1) or disable (0) ignoring the CloudBees Flow server host name mismatch.

--serverInitMemory=percent

Initial java heap size as a percentage of the total system memory.

--serverMaxMemory=percent

Maximum java heap size as a percentage of the total system memory.

--serverInitMemoryMB=size

Initial java heap size in MB.

--serverMaxMemoryMB=size

Maximum java heap size in MB.

--serverMaxThreadsApi=max

The size for the API thread pool. '0' means let the CloudBees Flow server decide.

--serverKeyFile=relativepath

Relative path of the CA key file used by the CloudBees Flow server to support SSL connections.

--serverKeystore=path

Relative location of the keystore file used by the CloudBees Flow server to support SSL connections.

--serverKeystorePassword=password

Password used to access the CloudBees Flow server’s keystore.

--serverLogClusterConnectionProblems=<true|false>

Enable (true) or disable (false) additional logging for the connection problems in the cluster environment.

--serverMaxThreadsDispatch=max

The size for the dispatch thread pool. '0' means let the CloudBees Flow server decide.

--serverMaxThreadsHttp=max

The size for the HTTP thread pool. '0' means let the CloudBees Flow server decide.

--serverMaxThreadsQuartz=max

The size for the quartz thread pool. '0' means let the CloudBees Flow server decide.

--serverMaxThreadsWorkflow=max

The size for the workflow thread pool. '0' means let the CloudBees Flow server decide.

--serverMonitoringEnabledDataDirectory=<true|false>

Enable (true) or disable (false) disk space monitoring for the data directory.

--serverMonitoringEnabledLogDirectory=<true|false>

Enable (true) or disable (false) disk space monitoring for the log directory.

--serverMonitoringEnabledMqDirectory=<true|false>

Enable (true) or disable (false) disk space monitoring for the message broker data directory.

--serverMqDataDirectory=path

The directory the CloudBees Flow server uses to store message broker data.

--serverMqDiskSpaceLimitHard=size

The limit of the free disk space when CloudBees Flow server will be switched in bootstrap mode, in MB.

--serverMqDiskSpaceLimitSoft=size

The limit of the free disk space when CloudBees Flow server will start to log warnings, in MB.

--serverMqDiskSpaceMonitoringEnabled=<true|false>

Enable (true) or disable (false) disk space monitoring for the message broker data storage.

--serverMqDiskSpaceMonitoringInClusterOnly=<true|false>

Enable (true) or disable (false) disk space monitoring for the message broker data storage only in cluster environment.

--serverNestedLdapGroupsMaxDepthLimit=max

Maximum allowed depth limit of nested LDAP groups

--serverPasskeyFile=path

Path to the server’s passkey file.

--serverProxyHost=host

The IP address of the proxy server.

--serverProxyPort=port

The port of the proxy server.

--serverNoProxyHosts=hosts

Comma delimited list of hosts that should be reached directly, bypassing the proxy server.

--serverEnableProxySettings=<1|0>

Enable (1) or disable (0) the proxy server configuration. If enabling for the first time, --serverProxyHost and --serverProxyPort must be specified.

--serverPreserveSessions=<1|0>

Enable (1) or disable (0) preserving sessions even if there is the CloudBees Flow server hostname mismatch.

--serverRestPort=port

The port for the REST documentation

--serverRestProtocol=<http|https>

The transfer protocol for the REST documentation.

--serverServicePrincipalName=name

The Kerberos Service Principal Name that will be used to authorize users. This command changes wrapper.java.additional.950 in the DATA_DIR/conf/wrapper.conf file.

--serverStatsdHost=host

The host of the statsd server the CloudBees Flow server uses to send data.

--serverStatsdPort=port

The port of the statsd server the CloudBees Flow server uses to send data.

--serverStatsdPrefix=string

The prefix the CloudBees Flow server uses in the data to the statsd server.

--serverStatsdIncludeHostname=<true|false>

Enable (true) or disable (false) inclusion of the CloudBees Flow server host to the prefix of the data sent to the statsd server.

--serverTLSEnabledProtocol < protocols >

Comma-delimited list of cryptographic protocols that will be allowed for CloudBees Flow server connections using HTTPS. The possible values are any combination of TLSv1, TLSv1.1, TLSv1.2, and SSLv2Hello.

The default security configurations are as follows:

We recommend removing the SSL 2.0 Client Hello or SSLv2Hello protocol from your security configurations for all components. When you do this, you would also need to upgrade older agents to the latest version to avoid security risks. You would need to upgrade agents if you are using the following agent versions:

--serverZooKeeperConnection=host:port[,host:port,host:port[,host:port,host:port]]

Comma-separated list of host IP/FQDN and ports for the ZooKeeper servers for a clustered configuration.

--serverExhibitorConnection=host[:port][,host,host[,host,host]]

Comma-separated list of host IP/FQDN for the Exhibitor servers for a clustered configuration, if you are using Exhibitor. To use a port number other than 80, add the port number after the first host IP/FQDN: the same port number will be used for all hosts.

--serverEnableClusteredMode=<1|0>

Enable (1) or disable (0) the clustered configuration. If enabling for the first time, --serverZooKeeperConnection must be specified.

--serverWrapperConsoleFormat=format

Format of output for the CloudBees Flow server wrapper console.

--serverWrapperJavaClasspath=n=path

The Java classpath. n must be an integer >= 1.

--serverWrapperJavaLibraryPath=n=path

The Java Library Path (location of Wrapper.DLL or libwrapper.so). n must be an integer >= 1.

--serverWrapperLogfile=path

Log file to use for the CloudBees Flow server wrapper output logging.

--serverWrapperLogfileFormat=format

Format of output for the CloudBees Flow server wrapper log file.

--serverWrapperLogfileLoglevel=loglevel

Log level for the CloudBees Flow server wrapper log file output.

--serverWrapperLogfileMaxfiles=max

Maximum number of rolled log files which will be allowed before old files are deleted.

--serverWrapperLogfileMaxsize=size

Maximum size that the log file will be allowed to grow to before the log is rolled. Size is specified in bytes, kilobytes with a 'k' suffix, or megabytes with an 'm' suffix.

--serverWrapperPingInterval=seconds

Java virtual machine-wrapper heartbeat interval, in seconds.

--serverWrapperPingTimeout=seconds

Java virtual machine-wrapper heartbeat timeout, in seconds.

--serverWrapperRequestThreadDumpOnFailedJvmExit=<true|false>

Whether to try to get a thread dump if the Java virtual machine doesn’t exit cleanly.

--serverWrapperStartupTimeout=seconds

The wrapper’s startup timeout, in seconds.

--serverWrapperShutdownTimeout=seconds

The wrapper’s shutdown timeout, in seconds.

--serverWrapperSuccessfulInvocationTime=seconds

The amount of time the CloudBees Flow server has to be up before the wrapper considers it a 'successful' invocation. If there are 5 or more consecutive failed invocations, the wrapper will no longer start up the CloudBees Flow server.

--serverWrapperSyslogLoglevel=loglevel

Log level for sys/event CloudBees Flow server wrapper log output.

--serverXmlReaderStripWhitespaceText=<true|false>

Enable (true) or disable (false) the clipping of the values of the UI-form parameters that contain only spaces.

--wrapperJavaAdditional=nnnnn=value

Set a line wrapper.java.additional=value in the server’s wrapper.conf file. nnnnn must be an integer >= 10000.

--databaseEnableService=<1|0>

Enable (1) or disable (0) the built-in database service.

--databaseMemoryBufferSize=size

Size of the database memory buffer. The value can be suffixed with a unit (K, M, or G). Without a unit, the value is interpreted as bytes. The default size is 256 MB.

--databasePassword=password

Password used to access the database. The default password is changeme.

--databasePort=port

Port used by the database. The default port is 8900.

--repositoryAcceptQueueSize=max

The maximum number of pending connections the repository server will queue up.

--repositoryAgentUrl=url

The agent URL to use for proxying server requests

--repositoryPort

The repository server port.

--repositoryIdleConnectionTimeout=milliseconds

The idle connection timeout, in milliseconds.

--repositoryKeystore=path

Location of the keystore file used by the repository server to support SSL connections from the CloudBees Flow server.

--repositoryKeystorePassword=password

Password used to access the repository server’s keystore.

--repositoryMaxConnections=max

The maximum number of total connections.

--repositoryMaxConnectionsPerRoute=max

The maximum number of connections to one machine.

--repositoryInitMemory=percent

Initial java heap size as a percentage of the total system memory.

--repositoryMaxMemory=percent

Maximum java heap size as a percentage of the total system memory.

--repositoryInitMemoryMB=size

Initial java heap size in MB.

--repositoryMaxMemoryMB=size

Maximum java heap size in MB.

--repositoryMaxHttpThreads=max

The maximum number of threads for handling inbound requests.

--repositoryStorageDirectory=path

Path to the repository backing store. The artifact repository will use this directory to store artifacts.

NOTE:

path cannot be a mapped drive path. For example, c:/repository-data is not allowed and will cause artifact publishing to fail. You must use a UNC path such as //10.0.109.72/repo_share/repository-data.

--repositoryTargetHostName=host

The host name of the CloudBees Flow server to which the repository server points.

--repositoryTargetHttpPort=port

The HTTP port of the CloudBees Flow server to which the repository server points.

--repositoryTargetHttpsPort=port

The HTTPS port of the CloudBees Flow server to which the repository server points.

--repositoryTargetProtocol=<http|https>

The protocol that the repository server uses to talk to the CloudBees Flow server.

--repositoryTLSEnabledProtocol < protocols >

Comma-delimited list of cryptographic protocols that will be allowed for CloudBees Flow repository server connections using HTTPS. The possible values are any combination of TLSv1, TLSv1.1, TLSv1.2, and SSLv2Hello.

The default security configurations are as follows:

We recommend removing the SSL 2.0 Client Hello or SSLv2Hello protocol from your security configurations for all components. When you do this, you would also need to upgrade older agents to the latest version to avoid security risks. You would need to upgrade agents if you are using the following agent versions:

--repositoryProtocol

The protocol that the repository server uses to talk to client applications.

--repositoryProxyHost=host

The IP address of the proxy server.

--repositoryProxyPort=port

The port of the proxy server.

--repositoryNoProxyHosts=hosts

Comma delimited list of hosts that should be reached directly, bypassing the proxy server.

--repositoryEnableProxySettings=<1|0>

Enable (1) or disable (0) the proxy server configuration. If enabling for the first time, --repositoryProxyHost and --repositoryProxyPort must be specified.

--repositoryValidateFromDisk=<1|0>

Enable (1) or disable (0) disk validation.

--repositoryWrapperConsoleFormat=format

Format of output for the repository server wrapper console.

--repositoryWrapperJavaClasspath=n=path

The Java classpath. n must be an integer >= 1.

--repositoryWrapperJavaLibraryPath=n=path

The Java Library Path (location of Wrapper.DLL or libwrapper.so). n must be an integer >= 1.

--repositoryWrapperLogfile=path

Log file to use for the repository server wrapper output logging.

--repositoryWrapperLogfileFormat=format

Format of output for the repository server wrapper log file.

--repositoryWrapperLogfileLoglevel=loglevel

Log level for the repository server wrapper log file output.

--repositoryWrapperLogfileMaxfiles=max

Maximum number of rolled log files which will be allowed before old files are deleted.

--repositoryWrapperLogfileMaxsize=size

Maximum size that the log file will be allowed to grow to before the log is rolled. Size is specified in bytes, kilobytes with a 'k' suffix, or megabytes with an 'm' suffix.

--repositoryWrapperPingInterval=seconds

Java virtual machine-wrapper heartbeat interval, in seconds.

--repositoryWrapperPingTimeout=seconds

Java virtual machine-wrapper heartbeat timeout, in seconds.

--repositoryWrapperRequestThreadDumpOnFailedJvmExit=<true|false>

Whether to try to get a thread dump if the Java virtual machine doesn’t exit cleanly.

--repositoryWrapperStartupTimeout=seconds

The wrapper’s startup timeout, in seconds.

--repositoryWrapperShutdownTimeout=seconds

The wrapper’s shutdown timeout, in seconds.

--repositoryWrapperSuccessfulInvocationTime=seconds

The amount of time the repository server has to be up before the wrapper considers it a 'successful' invocation. If there are 5 or more consecutive failed invocations, the wrapper will no longer start up the repository server.

--repositoryWrapperSyslogLoglevel=loglevel

Log level for sys/event repository server wrapper log output.

-v,--version

Display version information.

-h,--help

Display this information.

Commander Agent Configuration Options:

--agentAcceptQueueSize=max

The maximum number of pending connections the agent will queue up.

--agentArtifactCache=path

The directory containing cached artifactVersions.

--agentCaFile=path

A single file containing multiple CA certificates.

--agentCaPath=path

A directory containing a file for every CA, where each file’s name is the CA subject name hash value.

--agentCertFile=path

Location of the certificate file used by the agent to support SSL connections from the server.

--agentCrlFile=relativepath

Relative path of the file containing the agent’s certificate revocation list for SSL.

--agentDomainName=domain

The domain name that the agent uses for fully-qualified names.

--agentDuplicateDetectionListSize=size

The size of the list of recently seen requests used in duplicate request detection.

--agentEnableProxySettings=<1|0>

Enable (1) or disable (0) the proxy server configuration. If enabling for the first time, --agentProxyHost and --agentProxyPort must be specified.

--agentIdleConnectionTimeout=milliseconds

Idle connection timeout, in milliseconds.

--agentIdleOutboundConnectionTimeout=seconds

Idle time after which an outbound connection is closed, in seconds.

--agentIdlePostRunnerTimeout=seconds

Idle time after which a PostRunner thread is terminated, in seconds.

--agentIdleServerRequestWorkerTimeout=seconds

Idle time after which a ServerRequestWorker thread is terminated, in seconds

--agentIdleWorkerTimeout=seconds

Idle time after which a Worker thread is terminated, in seconds.

--agentInitMemory=percent

Initial java heap size as a percentage of the total system memory.

--agentInitMemoryMB=size

Initial java heap size in MB.

--agentKeyFile=path

Location of the key file used by the agent to support SSL connections from the server.

--agentKeystore=path

Location of the keystore file used by the agent to support SSL connections from the server.

--agentKeystorePassword=password

Password used to access the agent’s keystore.

--agentLoadProfile=<true|yes|1|false|no|0>

Enable (1) or disable (0) loading the impersonated user’s profile for impersonation steps if on Windows.

--agentLocalPort=port

Port used by the Commander agent for http communication on the localhost network interface.

--agentLogFile=path

Path where the C++ agent log file should be written.

--agentLogLevel=<TRACE|DEBUG|INFO|WARN|ERROR>

Logging level used by the C++ portion of the agent.

--agentLogMaxFiles=max

Maximum number of log files the C++ agent will accrue.

--agentLogMaxSize=max

Maximum size of each log file from the C++ agent. The value may be suffixed with a unit (MB, KB, B). Without a unit, the value is interpreted as bytes.

--agentMaxConnections=max

Maximum number of network connections for the agent.

--agentMaxConnectionsPerRoute=max

Maximum number of network connections per route for the agent.

--agentMaxHttpThreads=max

Maximum number of threads for handling inbound requests.

--agentMaxLoggedMessageLength=max

Maximum message length, used when logging requests/ responses to/from the CloudBees Flow server.

--agentMaxMemory=percent

Maximum java heap size as a percentage of the total system memory.

--agentMaxMemoryMB=size

Maximum java heap size in MB.

--agentNoProxyHosts=hosts

Comma delimited list of hosts that should be reached directly, bypassing the proxy server.

--agentOutboundConnectTimeout=milliseconds

Timeout for the agent establishing outbound connections, in milliseconds.

--agentOutboundRequestInitialRetryInterval=seconds

Initial delay between retries for sending outbound requests to a server, in seconds.

--agentOutboundRequestMaxRetryInterval=seconds

Maximum delay between retries for sending outbound requests to a server, in seconds.

--agentOutboundRequestTimeout=hours

Timeout after which the agent gives up trying to send a request to a server, in hours.

--agentPluginsDirectory=path

The path used by the agent to get to the plugins directory of the CloudBees Flow server where its resource definition lies.

--agentPort=port

Port used by the Commander agent for https communication on any network interface.

--agentProto=<http|https>

Protocol used internally by the agent.

--agentProtocol=<http|https>

Protocol used by the agent.

--agentProxyHost=host

The IP address of the proxy server.

--agentProxyPort=port

The port of the proxy server.

--agentServerConnectTimeout=seconds

Socket connection timeout for outbound requests to a server, in seconds.

--agentServerReadTimeout=seconds

Socket read timeout for responses from a server, in seconds.

--agentServerSessionsFile=relativepath

Relative path to the persisted server sessions file.

--agentUnixShellPattern=pattern

Windows-only: ordinarily, the agent creates script-files with CRLF line termination. But some shells on Windows require script files to be LF line-terminated, like Unix. This option sets a regular expression pattern for such shells. Defaults to a pattern that matches sh and bash, which in modern versions of Cygwin require LF-terminated script files.

--agentVerifyPeer=<true|yes|1|false|no|0>

Enable (1) or disable (0) verifying the certificate presented by the CloudBees Flow server when it connects.

--agentWrapperConsoleFormat=format

Format of output for the agent wrapper console.

--agentWrapperEcwrapperWriteMaxAttempts=max

Workspace write maximum attempts count

--agentWrapperEcwrapperWriteRetryInterval=milliseconds

Workspace write interval between two attempts, in milliseconds.

--agentWrapperJavaAdditional=nnnnn=value

Set a custom line of the form wrapper.java.additional.nnnnn=value in the agent’s wrapper.conf file. nnnnn must be an integer >= 10000.

--agentWrapperJavaClasspath=n=path

The Java classpath. n must be an integer >= 1.

--agentWrapperJavaLibraryPath=n=path

The Java Library Path (location of Wrapper.DLL or libwrapper.so). n must be an integer >= 1.

--agentWrapperLogfile=path

Log file to use for agent wrapper output logging.

--agentWrapperLogfileFormat=format

Format of output for the agent wrapper log file.

--agentWrapperLogfileLoglevel=loglevel

Log Level for agent wrapper log file output.

--agentWrapperLogfileMaxsize=size

Maximum size that the log file will be allowed to grow to before the log is rolled. Size is specified in bytes, kilobytes with a 'k' suffix, or megabytes with an 'm' suffix.

--agentWrapperLogfileMaxfiles=max

Maximum number of rolled log files which will be allowed before old files are deleted.

--agentWrapperNtserviceDependency=n=service

NT service dependencies. Add dependencies as needed starting from 1. n must be an integer >= 1.

--agentWrapperNtserviceStarttype=<AUTO_START|DEMAND_START>

Mode in which the NT service is installed.

--agentWrapperNtserviceInteractive=<true|false>

Whether to allow the NT service to interact with the desktop.

--agentWrapperPingInterval=seconds

Java virtual machine-wrapper heartbeat interval, in seconds.

--agentWrapperPingTimeout=seconds

Java virtual machine-wrapper heartbeat timeout, in seconds.

--agentWrapperRequestThreadDumpOnFailedJvmExit=<true|false>

Whether to try to get a thread dump if the Java virtual machine doesn’t exit cleanly.

--agentWrapperShutdownTimeout=seconds

The wrapper’s shutdown timeout, in seconds.

--agentWrapperStartupTimeout=seconds

The wrapper’s startup timeout, in seconds.

--agentWrapperSuccessfulInvocationTime=seconds

The amount of time the agent has to be up before the wrapper considers it a 'successful' invocation. If there are 5 or more consecutive failed invocations, the wrapper will no longer start up the agent.

--agentWrapperSyslogLoglevel=loglevel

Log Level for sys/event agent wrapper log output.

Apache Web Server Configuration Options:

--webHostName=host

The host name of the current machine in the form that users will typically use in their browser to access the web server.

--webHttpPort=port

The HTTP port of the web server.

--webHttpsPort=port

The HTTPS port of the web server.

--webTargetHostName=host

The host name of the CloudBees Flow server to which the web server points.

--webTargetHttpPort=port

The HTTP port of the CloudBees Flow server to which the web server points.

--webTargetHttpsPort=port

The HTTPS port of the CloudBees Flow server to which the web server points.

--webTimeZone=timezone

The Olson TimeZone format (example: America/Los Angeles) for the php web server.

--webPluginsDirectory=path

The path used by the web server to get to the plugins directory of the CloudBees Flow server to which it points.

--webProxyUrl=url

The IP address and port of the proxy server in the following format. https://<IP_ADDRESS_PROXY>:<PROXY_PORT>

--webNoProxyHosts=hosts

Comma delimited list of hosts that should be reached directly, bypassing the proxy server.

--webEnableProxySettings=<1|0>

Enable (1) or disable (0) the proxy server configuration. If enabling for the first time, --webProxyUrl must be specified.

--webDLC=url

The URL to use for downloadable content requests.

--webDisableHttpsRedirection=<1|0>

Disable (1) or enable (0) HTTP → HTTPS web redirection by the web server.

--webCsrfProtection=<true|false>

Enable (true) or disable (false) Cross-Site Request Forgery protection on the web server.CloudBees Flow server

Configuration Options:

--serverAcceptQueueSize=max

The maximum number of pending connections the CloudBees Flow server will queue up.

--serverBatchDbRequestsOverride=<1|0|auto>

Enable (1), disable (0) or let the server decide (auto) for using db request batching.

--serverBindIp=<ip or hostname>

The IP addess or host name the CloudBees Flow server listen to.

--serverCertFile=relativepath

Relative path of the certificate file used by the CloudBees Flow server to support SSL connections.

--serverChangeTrackingHardMaxRecords=number

The maximum number of records for change tracking

--serverCommanderPort=port

The HTTP port of the server.

--serverCommanderHttpsPort=port

The HTTPS port of the server.

--serverCriticalServicesMonitoringEnabled=<true|false>

Enable (true) or disable (false) monitoring for the critical services.

--serverCriticalServicesMonitoringFrequency=seconds

The interval between the critical services checks and the disk space checks, seconds.

--serverCrlFile=relativepath

Relative path of the file containing the CloudBees Flow server’s certificate revocation list for SSL.

--serverDatabaseName=name

The name of the database the CloudBees Flow server uses for its operation.

--serverDatabaseUsername=name

The user name for the database the CloudBees Flow server uses for its operation.

--serverFileTransferPort=port

The file transfer port of the server.

--serverForceEnableAdmin=<1|0>

Set to '1' or '0' to override the current value of the 'enableAdminUser' CloudBees Flow server setting.

--serverName=host

The name the CloudBees Flow server, usually its fully-qualified domain name, or for a cluster the fully-qualified domian name of the load balancer.

--serverHttpPort=port

The HTTP port of the server, default value 8000.

--serverHttpsPort=port

The HTTPS port of the server, default value 8443.

--serverIgnoreServerMismatch=<1|0>

Enable (1) or disable (0) ignoring the CloudBees Flow server hostname mismatch.

--serverInitMemory=percent

Initial java heap size as a percentage of the total system memory.

--serverMaxMemory=percent

Maximum java heap size as a percentage of the total system memory.

--serverInitMemoryMB=size

Initial java heap size in MB.

--serverMaxMemoryMB=size

Maximum java heap size in MB.

--serverMaxThreadsApi=max

The size for the API thread pool. '0' means let the CloudBees Flow server decide.

--serverKeyFile=relativepath

Relative path of the CA key file used by the CloudBees Flow server to support SSL connections.

--serverKeystore=path

Location of the keystore file used by the CloudBees Flow server to support SSL connections.

--serverKeystorePassword=password

Password used to access the CloudBees Flow server’s keystore.

--serverLogClusterConnectionProblems=<true|false>

Enable (true) or disable (false) additional logging for the connection problems in the cluster environment.

--serverMaxThreadsDispatch=max

The size for the dispatch thread pool. '0' means let the CloudBees Flow server decide.

--serverMaxThreadsHttp=max

The size for the HTTP thread pool. '0' means let the CloudBees Flow server decide.

--serverMaxThreadsQuartz=max

The size for the quartz thread pool. '0' means let the CloudBees Flow server decide.

--serverMaxThreadsWorkflow=max

The size for the workflow thread pool. '0' means let the CloudBees Flow server decide.

--serverMonitoringEnabledDataDirectory=<true|false>

Enable (true) or disable (false) disk space monitoring for the data directory.

--serverMonitoringEnabledLogDirectory=<true|false>

Enable (true) or disable (false) disk space monitoring for the log directory.

--serverMonitoringEnabledMqDirectory=<true|false>

Enable (true) or disable (false) disk space monitoring for the message brocker data directory.

--serverMqDataDirectory=path

The directory the CloudBees Flow server uses to store message broker data.

--serverMqDiskSpaceLimitHard=size

The limit of the free disk space when CloudBees Flow server will be switched in bootstrap mode, in MB.

--serverMqDiskSpaceLimitSoft=size

The limit of the free disk space when CloudBees Flow server will start to log warnings, in MB.

--serverMqDiskSpaceMonitoringEnabled=<true|false>

Enable (true) or disable (false) disk space monitoring for the message broker data storage.

--serverMqDiskSpaceMonitoringInClusterOnly=<true|false>

Enable (true) or disable (false) disk space monitoring for the message broker data storage only in cluster environment.

--serverNestedLdapGroupsMaxDepthLimit=max

Maximum allowed depth limit of nested LDAP groups

--serverPasskeyFile=path

Path to the server’s passkey file.

--serverProxyHost=host

The IP address of the proxy server.

--serverProxyPort=port

The port of the proxy server.

--serverNoProxyHosts=hosts

Comma delimited list of hosts that should be reached directly, bypassing the proxy server.

--serverEnableProxySettings=<1|0>

Enable (1) or disable (0) the proxy server configuration. If enabling for the first time, --serverProxyHost and --serverProxyPort must be specified.

--serverPreserveSessions=<1|0>

Enable (1) or disable (0) preserving sessions even if there is the CloudBees Flow server hostname mismatch.

--serverRestPort=port

The port for the REST documentation

--serverRestProtocol=<http|https>

The transfer protocol for the REST documentation.

--serverStatsdHost=host

The host of the statsd server the CloudBees Flow server uses to send data.

--serverStatsdPort=port

The port of the statsd server the CloudBees Flow server uses to send data.

--serverStatsdPrefix=string

The prefix the CloudBees Flow server uses in the data to the statsd server.

--serverStatsdIncludeHostname=<true|false>

Enable (true) or disable (false) inclusion of the CloudBees Flow server host to the prefix of the data sent to the statsd server.

--serverEnableStatsdServer=<1|0>

Enable (1) or disable (0) the statsd server configuration. If enabling for the first time, --serverStatsdHost must be specified.

--serverZooKeeperConnection=host:port[,host:port,host:port[,host:port,host:port]]

Comma-separated list of host IP/FQDN and ports for the ZooKeeper servers for a clustered configuration.

--serverExhibitorConnection=host[:port][,host,host[,host,host]]

Comma-separated list of host IP/FQDN for the Exhibitor servers for a clustered configuration, if you are using Exhibitor. To use a port number other than 80, add the port number after the first host IP/FQDN: the same port number will be used for all hosts.

--serverEnableClusteredMode=<1|0>

Enable (1) or disable (0) the clustered configuration. If enabling for the first time, --serverZooKeeperConnection must be specified.

--serverWrapperConsoleFormat=format

Format of output for the CloudBees Flow server wrapper console.

--serverWrapperJavaClasspath=n=path

The Java classpath. n must be an integer >= 1.

--serverWrapperJavaLibraryPath=n=path

The Java Library Path (location of Wrapper.DLL or libwrapper.so). n must be an integer >= 1.

--serverWrapperLogfile=path

Log file to use for the CloudBees Flow server wrapper output logging.

--serverWrapperLogfileFormat=format

Format of output for the CloudBees Flow server wrapper log file.

--serverWrapperLogfileLoglevel=loglevel

Log level for the CloudBees Flow server wrapper log file output.

--serverWrapperLogfileMaxfiles=max

Maximum number of rolled log files which will be allowed before old files are deleted.

--serverWrapperLogfileMaxsize=size

Maximum size that the log file will be allowed to grow to before the log is rolled. Size is specified in bytes, kilobytes with a 'k' suffix, or megabytes with an 'm' suffix.

--serverWrapperPingInterval=seconds

Java virtual machine-wrapper heartbeat interval, in seconds.

--serverWrapperPingTimeout=seconds

Java virtual machine-wrapper heartbeat timeout, in seconds.

--serverWrapperRequestThreadDumpOnFailedJvmExit=<true|false>

Whether to try to get a thread dump if the Java virtual machine doesn’t exit cleanly.

--serverWrapperStartupTimeout=seconds

The wrapper’s startup timeout, in seconds.

--serverWrapperShutdownTimeout=seconds

The wrapper’s shutdown timeout, in seconds.

--serverWrapperSuccessfulInvocationTime=seconds

The amount of time the CloudBees Flow server has to be up before the wrapper considers it a 'successful' invocation. If there are 5 or more consecutive failed invocations, the wrapper will no longer start up the CloudBees Flow server.

--serverWrapperSyslogLoglevel=loglevel

Log level for sys/event CloudBees Flow server wrapper log output.

--serverXmlReaderStripWhitespaceText=<true|false>

Enable (true) or disable (false) the clipping of the values of the UI-form parameters that contain only spaces.

--wrapperJavaAdditional=nnnnn=value

Set a line wrapper.java.additional=value in the server’s wrapper.conf file. nnnnn must be an integer >= 10000.

MySQL Database Configuration Options:

--databaseMemoryBufferSize=size

Size of the database memory buffer The value may be suffixed with a unit (K, M, G). Without a unit, the value is interpreted as bytes.

--databasePort

The database port.

Repository Server Configuration Options:

--repositoryAcceptQueueSize=max

The maximum number of pending connections the repository server will queue up.

--repositoryAgentUrl=url

The agent URL to use for proxying server requests

--repositoryPort

The repository server port.

--repositoryIdleConnectionTimeout=milliseconds

The idle connection timeout, in milliseconds.

--repositoryKeystore=path

Location of the keystore file used by the repository server to support SSL connections from the CloudBees Flow server.

--repositoryKeystorePassword=password

Password used to access the repository server’s keystore.

--repositoryMaxConnections=max

The maximum number of total connections.

--repositoryMaxConnectionsPerRoute=max

The maximum number of connections to one machine.

--repositoryInitMemory=percent

Initial java heap size as a percentage of the total system memory.

--repositoryMaxMemory=percent

Maximum java heap size as a percentage of the total system memory.

--repositoryInitMemoryMB=size

Initial java heap size in MB.

--repositoryMaxMemoryMB=size

Maximum java heap size in MB.

--repositoryMaxHttpThreads=max

The maximum number of threads for handling inbound requests.

--repositoryStorageDirectory=path

Path to the repository backing store. The artifact repository will use this directory to store artifacts.

--repositoryTargetHostName=host

The host name of the CloudBees Flow server to which the repository server points.

--repositoryTargetHttpPort=port

The HTTP port of the CloudBees Flow server to which the repository server points.

--repositoryTargetHttpsPort=port

The HTTPS port of the CloudBees Flow server to which the repository server points.

--repositoryTargetProtocol=<http|https>

The protocol that the repository server uses to talk to the CloudBees Flow server.

--repositoryProtocol

The protocol that the repository server uses to talk to client applications.

--repositoryProxyHost=host

The IP address of the proxy server.

--repositoryProxyPort=port

The port of the proxy server.

--repositoryNoProxyHosts=hosts

Comma delimited list of hosts that should be reached directly, bypassing the proxy server.

--repositoryEnableProxySettings=<1|0>

Enable (1) or disable (0) the proxy server configuration. If enabling for the first time, --repositoryProxyHost and --repositoryProxyPort must be specified.

--repositoryValidateFromDisk=<1|0>

Enable (1) or disable (0) disk validation.

--repositoryWrapperConsoleFormat=format

Format of output for the repository server wrapper console.

--repositoryWrapperJavaClasspath=n=path

The Java classpath. n must be an integer >= 1.

--repositoryWrapperJavaLibraryPath=n=path

The Java Library Path (location of Wrapper.DLL or libwrapper.so). n must be an integer >= 1.

--repositoryWrapperLogfile=path

Log file to use for the repository server wrapper output logging.

--repositoryWrapperLogfileFormat=format

Format of output for the repository server wrapper log file.

--repositoryWrapperLogfileLoglevel=loglevel

Log level for the repository server wrapper log file output.

--repositoryWrapperLogfileMaxfiles=max

Maximum number of rolled log files which will be allowed before old files are deleted.

--repositoryWrapperLogfileMaxsize=size

Maximum size that the log file will be allowed to grow to before the log is rolled. Size is specified in bytes, kilobytes with a 'k' suffix, or megabytes with an 'm' suffix.

--repositoryWrapperPingInterval=seconds

Java virtual machine-wrapper heartbeat interval, in seconds.

--repositoryWrapperPingTimeout=seconds

Java virtual machine-wrapper heartbeat timeout, in seconds.

--repositoryWrapperRequestThreadDumpOnFailedJvmExit=<true|false>

Whether to try to get a thread dump if the Java virtual machine doesn’t exit cleanly.

--repositoryWrapperStartupTimeout=seconds

The wrapper’s startup timeout, in seconds.

--repositoryWrapperShutdownTimeout=seconds

The wrapper’s shutdown timeout, in seconds.

--repositoryWrapperSuccessfulInvocationTime=seconds

The amount of time the repository server has to be up before the wrapper considers it a 'successful' invocation. If there are 5 or more consecutive failed invocations, the wrapper will no longer start up the repository server.

--repositoryWrapperSyslogLoglevel=loglevel

Log level for sys/event repository server wrapper log output.

General Options:

-v,--version

Display version information.

-h,--help

Display this information

Description

Computes the default working directory where a command needs to run on the proxy target, if the step is not defined with a working directory.

Arguments

None

Returns

The path to a directory as it would be accessed on the proxy target.

SSH implementation function

Not SSH-specific, so the function is ' getDefaultWorkingDirectory '

Existing implementation

Return $ENV{COMMANDER_WORKSPACE_UNIX};

Reason to override

If the "Working Directory" field is empty on a step that is going to run on a proxy target, the working directory for the step should be the workspace, just as it would be if the step were running on a non-proxy CloudBees Flow agent. ecproxy is guaranteed to run in the workspace directory on the proxy agent, but it is not guaranteed that the proxy target has the same path to the workspace. For example, the workspace on a Windows proxy agent is not the same as the path a Unix proxy target uses to access the workspace—so the existing implementation of this operation simply returns the UNIX path to the workspace. However, if the proxy target has a different path for accessing the workspace, the existing implementation will give the wrong answer. Thus, a user can provide a different implementation that gives the right answer.

Description

Computes the default port where the proxy target is listening for this protocol.

Arguments

None

Returns

The default port.

SSH implementation function

ssh_getDefaultTargetPort

Description

Opens a connection to the proxy target using the desired protocol.

Arguments

host, port (optional)

Returns

"connection-context hash-ref" on successful connection. This context can contain anything other functions can use to perform their tasks (for example, a connection handle).

Example 1

my $context =< connect('myhost', 22)

Example 2

my $context =< connect('myhost')

SSH implementation function

ssh_connect

Description

Uploads the given srcFile ` to the proxy target as `tgtFile.

Arguments

context, `srcFile ` (typically simple file-name), `tgtFile ` (typically workingDirectory/file-name)

Returns

Nothing; on failure it does a 'die' with an appropriate error message.

Example

uploadFile($context, 'agent123.tmp', '/opt/work/joe/agent123.tmp')

SSH implementation function

ssh_uploadFile

Description

Generates the script body that will run the command-file on the proxy-target in the workingDirectory.

Arguments

workingDirectory, cmd, cmdArg1, …​, cmdFileName (just the base-name, no directory)

Returns

A string containing the script to execute on the proxy target.

Example

generateWrapperScript('/opt/work/joe', 'perl', 'agent123.tmp'

SSH implementation function

Not SSH-specific, so the function is ` 'generateWrapperScript'`

Existing implementation

cd workingDirectory; set COMMANDER_ environment variables; run command-file, properly quoting the command and args.

Reason to override

If the proxy target does not have sh, the wrapper script needs to be written in a language available on the target.

Description

Uploads the wrapper-script code to the proxy target.

Arguments

context workingDirectory. wrapperScriptBody

Returns

The path to the wrapper-script on the proxy target.

Example

my $wrapperFile =< uploadWrapperScript($context, '/opt/work/joe', 'cd /opt/work/joe; perl agent123.tmp')

SSH implementation function

3.1, 3.1.1: ssh_uploadWrapperScript

3.1.2 and later

Not SSH-specific anymore, so the function is ` 'uploadWrapperScript'`

Description

Generates the command-line for running the wrapper script on the proxy target.

Arguments

remoteWrapperFile (path on proxy target)

Returns

A string containing the command-line for running the wrapper script file on the proxy target.

Example

my $wrapperCmdLine =< generateWrapperInvocationCommand($wrapperFile)

SSH implementation function

Not SSH-specific, so the function is 'generateWrapperInvocationCommand'

Existing implementation

Return "sh $remoteWrapperFile";

Reason to override

The default implementation of this function returns something like 'sh $wrapperFile'. If the wrapper script is not an `sh ` script, or if you want to pass different arguments to the shell, you must override this function.

Description

Runs the given command-line on the proxy target.

Arguments:

context, cmdLine

Returns

exit-code from running the command on the proxy target, `undef ` if the command could not be run for some reason.

Example

runCommand($context, $wrapperCmdLine)

SSH implementation function

ssh_runCommand

Description

Performs any cleanup task after the command has completed on the proxy target. Typically, it deletes any locally created temp files and uploaded files on the proxy target.

Arguments

context, cmdFile, wrapperFile ` (both are of the form `workingDirectory/file-name )

Returns

1 on success, undef ` on failure. `

Example

cleanupTarget($context, '/opt/work/joe/agent123.tmp', '/opt/work/joe/cmdwrapper.123.tmp')

SSH implementation function

3.1, 3.1.1: ssh_cleanup

3.1.2 and later

Not SSH-specific anymore, so the function is cleanup

Description

A test to see if the proxy target is usable.

Arguments

host, `port ` (optional)

Returns

1 on success, `undef ` on failure. ` `

Example

ping('myhost', 22)

SSH implementation function

Not SSH-specific, so the function is ping.

Existing implementation

Opens a socket connection to the proxy target on the desired port.

Reason to override

The existing implementation may be deemed too simple for doing a ping; overriding ping to open a connection and do some protocol-specific handshaking might be more appropriate for some protocols / use cases.

Description

Debug logging function. Writes to the file referenced in the ECPROXY_DEBUGFILE environment variable (if it exists). No-op otherwise.

Arguments

`message `

Example

mesg("myCleanup: about to delete $cmdFile on proxy target");

Description

Reads a file.

Arguments

fileName

Returns

Contents of the file. If there is an error, it returns an empty string.

Example

my $data =< readFile("foo.txt");

Description

Creates a local file containing data.

Arguments

fileName, data

Returns

1 on success, undef ` on failure. `

Example

writeFile("myWrapper.$ENV{COMMANDER_JOBSTEPID}.cmd", "perl foo.pl")

Description

Initialize the operation dispatcher map to point to functions for the given protocol. For each operation, initDispatcher ` checks if a function named `protocol_operation exists, and if so, assigns that function as the implementation for that operation.

Arguments

protocol

Example

initDispatcher("ssh") sets the "connect" operation to run "ssh_connect", "uploadFile" =<> "ssh_uploadFile", etc.

Description

Sets the implementation of an operation to be a particular function.

Arguments

operation, function. The 'function' argument may be the name of a function or a reference to a function.

Example

setOperation("ping", "my_ping"); sets the "ping" operation to run the "my_ping" function

Example

setOperation("ping", \&my_ping); same as above, but using a function ref

Description

Load proxy customizations from a file.

Arguments

fileName

Example

loadFile("custom.pl")

Description

Set the paths to the public and private key files that ssh will use to authenticate with the proxy target.

Arguments

publicKeyFile, privateKeyFile

Example

setSSHKeyFiles('c:\foo\pub.key', 'c:\foo\priv.key')

Description

Set the name of the user to authenticate with the proxy target.

Arguments

userName

Example

setSSHUser('user1')

Description

Normally, ecproxy uses one ssh session with a number of "channels" to perform tasks like uploading files, running the command, and running a cleanup command on the proxy target. Some SSH servers don’t allow this. This method configures ecproxy to use a separate SSH session for each operation; this requires authenticating with the SSH daemon on the proxy target several times, and thus it may perform worse than the single-session-multi-channel mode.

Arguments

None

Example

useMultipleSSHSessions()