Server Management

deleteLicense

Deletes a license.

You must specify a productName and featureName.

Arguments Descriptions

Arguments	Descriptions
productName	The name of the product with the licensed feature. Possible products include: `CloudBees CD/RO `. Argument type: String
featureName	The name of the licensed feature. Possible features include: `Server`. Argument type: String

productName

The name of the product with the licensed feature. Possible products include: `CloudBees CD/RO `.

Argument type: String

featureName

The name of the licensed feature. Possible features include: Server.

Argument type: String

Positional arguments

productName, featureName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteLicense(<productName>, <featureName>);

Example

$cmdr->deleteLicense("{PRODUCT} ", "Server");▼

ectool

syntax: ectool deleteLicense <productName> <featureName>

Example

ectool deleteLicense "{PRODUCT} " "Server"▼

getAdminLicense

Retrieves the admin license, which can be used when all concurrent user licenses are in use.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None.

Response

You can receive one or more responses, depending on how you are licensed and actual license usage at the time of your query.

Response examples:

When the user does not have the necessary permission to use the Administrator license:

    <error requestId="1">
        <code>AccessDenied</code>
        <where></where>
        <message>Principal '\bob@example.com' does not have execute privileges on
              systemObject[name=licensing,id=10]</message>
        <details></details>
    </error>▼

When the user has permission to get/use the Administrator license, but already has a User license:

` <result>User 'bob@example.com@192.168.17.217' already has an active license.</result>`

When the user has permission to use/get the Administrator license, has no other license, and the Administrator license is not currently assigned:

` <result>User 'bob@example.com@192.168.17.217' was given the admin license.</result>`

When the user has permission to get/use the Administrator license, has no license, and the Administrator license is currently assigned to someone else:

` <result>User 'joedoe@example.com@192.168.17.217' was given the admin license that previously belonged to 'bob@example.com@192.168.17.217'. </result>`

ec-perl

syntax: $cmdr->getAdminLicense();

Example

$cmdr->getAdminLicense();▼

ectool

syntax: ectool getAdminLicense

Example

ectool getAdminLicense▼

getCertificates

Returns the certificates in the trust chain for the server.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None.

Response

None or a status OK message.

ec-perl

syntax: $cmdr->getCertificates ();

Examples

$cmdr->getCertificates ();▼

ectool

syntax: `ectool getCertificates `

Examples

ectool getCertificates▼

getLicense

Retrieves information for one license.

You must specify the productName and featureName.

Arguments Descriptions

Arguments	Descriptions
featureName	The name of the licensed feature. Possible features include: `Server` Argument: String
productName	The name of the product with the licensed feature. Possible products include: ` CloudBees CD/RO ` Argument: String

featureName

The name of the licensed feature. Possible features include: Server

Argument: String

productName

The name of the product with the licensed feature. Possible products include: ` CloudBees CD/RO `

Argument: String

Positional arguments

productName, featureName

Response

One license element.

ec-perl

syntax: $cmdr->getLicense(<productName>, <featureName>);

Example

$cmdr->getLicense('{PRODUCT} ', 'Server');▼

ectool

syntax: ectool getLicense <productName> <featureName>

Example

ectool getLicense "{PRODUCT} " "Server"▼

getLicenses

Retrieves all license data.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None.

Response

Zero or more license elements.

ec-perl

syntax: $cmdr->getLicenses();

Example

$cmdr->getLicenses();▼

ectool

syntax: ectool getLicenses

Example

ectool getLicenses▼

getLicenseUsage

Retrieves the current license usage.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None.

Response

You may receive one or more responses for licenseUsage, depending on how you are licensed and actual license usage at the time of your query.

ec-perl

syntax: $cmdr->getLicenseUsage();

Example

$cmdr->getLicenseUsage();▼

ectool

syntax: ectool getLicenseUsage

Example

ectool getLicenseUsage▼

getServerInfo

Retrieves information about server ports and message delivery.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None.

Response

Returns the information about server ports and message delivery.

ec-perl

syntax: $cmdr->getServerInfo;

Examples

$cmdr->getServerInfo();▼

ectool

syntax: ectool getServerInfo

Examples

ectool getServerInfo▼

getServerStatus

Retrieves the current status of the CloudBees CD/RO server, including log messages generated during the startup sequence.

Arguments Descriptions

Arguments	Descriptions
block	(Optional) < Boolean flag— `0\|1\|true\|false` > If the argument is set to `1` or `true`, the system waits until the server reaches a terminal state . Terminal states include `running`, `failed`, `stopping`, and `importFailed`. Argument: Boolean
diagnostics	(Optional) < Boolean flag - ` 0\|1\|true\|false` > Select the diagnostic information that you want in your output: `threadDump` –stack dumps of all threads in the server `statistics` –output from all system timers `systemProperties` –values of all java system properties `environmentVariables` –values of all environment variables `settings` –values of all server settings `serverInfo` –output from `getServerInfo` call. Argument: Boolean
serverStateOnly	(Optional)< Boolean flag - ` 0\|1\|true\|false` > If the argument is set to `1` or `true`, the system limits the response to the short form and causes ectool to return only the value of the `serverStatus` element as a simple string value. Argument: Boolean
timeout	(Optional) This argument specifies the timeout for the `element` flag. The default value is 120 seconds. Argument: Integer

block

(Optional) < Boolean flag— 0|1|true|false >

If the argument is set to 1 or true, the system waits until the server reaches a terminal state . Terminal states include running, failed, stopping, and importFailed.

Argument: Boolean

diagnostics

(Optional) < Boolean flag - ` 0|1|true|false` >

Select the diagnostic information that you want in your output:

threadDump –stack dumps of all threads in the server
statistics –output from all system timers
systemProperties –values of all java system properties
environmentVariables –values of all environment variables
settings –values of all server settings
serverInfo –output from getServerInfo call.

Argument: Boolean

serverStateOnly

(Optional)< Boolean flag - ` 0|1|true|false` >

If the argument is set to 1 or true, the system limits the response to the short form and causes ectool to return only the value of the serverStatus element as a simple string value.

Argument: Boolean

timeout

(Optional) This argument specifies the timeout for the element flag.

The default value is 120 seconds.

Argument: Integer

Positional arguments

None.

Response

Returns the current status of the server, including the log message generated during the startup sequence. This command returns different information depending on when and how it is called.

You will get a lengthy response if you connect with a session that has admin privileges or if the server is still in a bootstrap state. After the server enters the "running" state, it is able to perform access checks but displays only the short form until you log in.

A simple response:

<serverState>running</serverState>

For more detailed server status response information, click here .

ec-perl

syntax: $cmdr->getServerStatus({<optionals>});

Examples

$cmdr->getServerStatus();
$cmdr->getServerStatus({diagnostics=>1});▼

ectool

syntax: ectool getServerStatus

Examples

ectool getServerStatus
ectool getServerStatus --diagnostics 1▼

getVersions

Retrieves server version information.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None

Response

A serverVersion element.

ec-perl

syntax: $cmdr->getVersions();

Example

$cmdr->getVersions();▼

ectool

syntax: ectool getVersions

Example

ectool getVersions▼

importLicenseData

Imports one or more licenses.

You must specify licenseData.

Arguments Descriptions

Arguments	Descriptions
licenseData	The content of a license file ( `perl\|XML API` ).
licenseFile	< localFileName > The license fie to import. This is a local file that will be read by ectool. The contents is sent as the `licenseData` argument (ectool only).

licenseData

The content of a license file ( perl|XML API ).

licenseFile

< localFileName > The license fie to import. This is a local file that will be read by ectool. The contents is sent as the licenseData argument (ectool only).

Positional arguments

licenseData

Response

None or a status OK message.

ec-perl

syntax: $cmdr->importLicenseData(<licenseData>)

Example

my $data = 'cat license.xml';
 $cmdr\->importLicenseData ($data);▼

ectool

syntax: ectool importLicenseData <licenseData>

Example

ectool importLicenseData license.xml▼

logMessage

Enters a message in the server log.

Arguments Descriptions

Arguments	Descriptions
message	Message to add to the server log. Argument: String
level	(Optional) Select a message level: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `OFF`. Argument: String
logger	(Optional) Name of the object that logged the message. Argument: String

message

Message to add to the server log.

Argument: String

level

(Optional) Select a message level: TRACE, DEBUG, INFO, WARN, ERROR, or OFF.

Argument: String

logger

(Optional) Name of the object that logged the message.

Argument: String

Positional arguments

message

Response

None or a status OK message.

ec-perl

syntax: $cmdr->logMessage (<message>, <optionals>});

Examples

$cmdr->logMessage ("abort job step" {level => INFO});▼

ectool

syntax: ectool logMessage <message> [optionals]

Examples

ectool logMessage "abort job step" --level INFO▼

setLogLevel

Changes the log level of a logger.

Arguments Descriptions

Arguments	Descriptions
logger	Name of the user or resource that logged the message. Argument: String
level	Select a message level: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `OFF`. Argument: String

logger

Name of the user or resource that logged the message.

Argument: String

level

Select a message level: TRACE, DEBUG, INFO, WARN, ERROR, or OFF.

Argument: String

Positional arguments

logger, level

Response

None or a status OK message.

ec-perl

syntax: $cmdr->setLogLevel(<logger>, <level>);

Examples

$cmdr->setLogLevel ("Test Lab 1", INFO);▼

ectool

syntax: ectool setLogLevel <logger> <level>

Examples

ectool setLogLevel "Test Lab 1" INFO▼

shutdownServer

Shuts down the CloudBees CD/RO server. Shutting down the server can take as long as a couple of minutes, depending on the server activity level at the time the shutdown command is issued.

The CloudBees CD/RO server is composed of two processes. The main process is a Java Virtual Machine (JVM). The second process, called the "wrapper", is responsible for interacting with the native operating system as a service. This wrapper process is responsible for starting and stopping the main JVM process.

Arguments Descriptions

Arguments	Descriptions
force	(Optional) < Boolean flag— `0\|1\|true\|false` > The "1" flag tells the CloudBees CD/RO server to exit immediately, without performing any of the usual associated cleanup activities. This action "kills" all running jobs. Argument: Boolean
restart	(Optional) < Boolean flag— `0\|1\|true\|false` > The "1" flag tells the CloudBees CD/RO server to shut down normally and immediately start again. Argument: Boolean

force

(Optional) < Boolean flag— 0|1|true|false > The "1" flag tells the CloudBees CD/RO server to exit immediately, without performing any of the usual associated cleanup activities. This action "kills" all running jobs.

Argument: Boolean

restart

(Optional) < Boolean flag— 0|1|true|false > The "1" flag tells the CloudBees CD/RO server to shut down normally and immediately start again.

Argument: Boolean

Positional arguments

None

Response

None or a status OK message.

ec-perl

syntax: $cmdr->shutdownServer({<optionals>});

Example

$cmdr->shutdownServer({restart => 1});▼

ectool

syntax: ectool shutdownServer [optionals]

Example

ectool shutdownServer --restart 1▼

tunePerformance

Adjusts how the server is performing.

Arguments Descriptions

Arguments	Descriptions
apiQueueSize	Maximum number of threads that will be created in the API thread pool. Argument: Integer
dbConnectionPoolSize	Maximum number of database connections that the server will use. Argument: Integer
dbThreadPoolSize	Number of worker threads in the database connection manager. Argument: Integer
dispatchQueueSize	Maximum number of threads that will be created in the Dispatch thread pool. Argument: Integer
quartzQueueSize	Maximum number of threads that will be created in the Quartz thread pool. Argument: Integer
stateMachineQueueSize	Maximum number of threads that will be created in the `stateMachine` thread pool. Argument: Integer

apiQueueSize

Maximum number of threads that will be created in the API thread pool.

Argument: Integer

dbConnectionPoolSize

Maximum number of database connections that the server will use.

Argument: Integer

dbThreadPoolSize

Number of worker threads in the database connection manager.

Argument: Integer

dispatchQueueSize

Maximum number of threads that will be created in the Dispatch thread pool.

Argument: Integer

quartzQueueSize

Maximum number of threads that will be created in the Quartz thread pool.

Argument: Integer

stateMachineQueueSize

Maximum number of threads that will be created in the stateMachine thread pool.

Argument: Integer

Positional arguments

None

Response

None or a status OK message.

ec-perl

syntax: $cmdr->tunePerformance ({<optionals>});

Examples

$cmdr->tunePerformance ({apiQueueSize => 4, dbConnectionPoolSize => 2});▼

ectool

syntax: ectool tunePerformance [optionals]

Examples

ectool tunePerformance --apiQueueSize 4 --dbConnectionPoolSize 2▼

getSsoConfiguration

Get SSO configurations for SSO type set with setSsoConfiguration.

Arguments Descriptions

Arguments	Descriptions
enableSsoKerberos	(Optional) Enable or disable SSO for Kerberos. Default is `false`. Argument Type: Boolean
enableSsoOpenIDConnect	(Optional) Enable or disable SSO for OpenId Connect. Default is `false`. Argument Type: Boolean
enableSsoSaml	(Optional) Enable or disable SSO for SAML. Default is `false`. Argument Type: Boolean

enableSsoKerberos

(Optional) Enable or disable SSO for Kerberos. Default is false.

Argument Type: Boolean

enableSsoOpenIDConnect

(Optional) Enable or disable SSO for OpenId Connect. Default is false.

Argument Type: Boolean

enableSsoSaml

(Optional) Enable or disable SSO for SAML. Default is false.

Argument Type: Boolean

Positional arguments

None.

Request and Response

ectool setSsoConfiguration --enableSsoOpenIDConnect true
ectool getSsoConfiguration▼

<response requestId="1" nodeId="172.17.0.1">
    <ssoKerberosEnabled>0</ssoKerberosEnabled>
    <ssoOpenIDConnectEnabled>1</ssoOpenIDConnectEnabled>
    <ssoSamlEnabled>0</ssoSamlEnabled>
    <openIDConnectConfigurations>
      <openIDConnectConfiguration>
        <openIDConnectConfigurationId>ac5bcb41-fe8e-11eb-a822-c2153bca2a26</openIDConnectConfigurationId>
        <openIDConnectConfigurationName>Okta</openIDConnectConfigurationName>
        <createTime>2021-08-16T12:37:09.540Z</createTime>
        <enableSingleLogout>1</enableSingleLogout>
        <enabled>1</enabled>
        <lastModifiedBy>admin</lastModifiedBy>
        <modifyTime>2021-08-16T12:37:09.540Z</modifyTime>
        <owner>admin</owner>
      </openIDConnectConfiguration>
    </openIDConnectConfigurations>
  </response>▼

setSsoConfiguration

Sets the SSO server configuration for use by getSsoConfiguration.

You must specify one of enableSsoKerberos, enableSsoOpenIDConnect, or enableSsoSaml.

Arguments Descriptions

Arguments	Descriptions
enableSsoKerberos	(Optional) Enable or disable SSO for Kerberos. Default is `false`. Argument Type: Boolean
enableSsoOpenIDConnect	(Optional) Enable or disable SSO for OpenId Connect. Default is `false`. Argument Type: Boolean
enableSsoSaml	(Optional) Enable or disable SSO for SAML. Default is `false`. Argument Type: Boolean

enableSsoKerberos

(Optional) Enable or disable SSO for Kerberos. Default is false.

Argument Type: Boolean

enableSsoOpenIDConnect

(Optional) Enable or disable SSO for OpenId Connect. Default is false.

Argument Type: Boolean

enableSsoSaml

(Optional) Enable or disable SSO for SAML. Default is false.

Argument Type: Boolean

Positional arguments

None.

Response

None.

ec-perl

syntax: $<object>->setSsoConfiguration({<optionals>});

Example

$ec->setSsoConfiguration({enableSsoKerberos => "true"});▼

ectool

syntax: ectool setSsoConfiguration [optionals]

Example

ectool setSsoConfiguration --enableSsoSaml "true"▼