Server Management

6 minute readReference

deleteLicense

Deletes a license.

You must specify a productName and featureName.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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.

ArgumentsDescriptions

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].

ArgumentsDescriptions

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 [getSssConfiguration].

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

ArgumentsDescriptions

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"