POST /command/create-connection

Create a new connection entry in the node inventory service database.

Request format

Connection database entries contain connection settings, such as certnames, transport methods, and credentials, that are used to connect to nodes (identified by their certnames).

When Forming node inventory API requests to this endpoint, the request body must be a JSON object that uses these required keys:

  • certnames: An array containing a list of certnames to associate with the supplied connection details.
  • type: A string that is either ssh or winrm. This tells bolt-server which connection type to use to access the node when running a task.
  • parameters: An object containing key/value pairs specifying the connection parameters for the specified transport type. Required and optional parameters depend on the transport method and are described further below.
    When the Puppet orchestrator targets a certname to run a task, it first considers the value of the hostname key present in the connection parameters, if supplied. Otherwise, it uses the value of the certnames key as the hostname. Make sure to include the hostname key only when the hostname differs from the certname. If you're configuring multiple connections (certnames) at once, do not include a hostname key.
  • sensitive_parameters: An object containing key/value pairs defining the necessary sensitive data for connecting to the provided certnames, such as usernames and passwords. These values are stored in an encrypted format. Required and optional parameters depend on the transport method and are described further below.
  • duplicates: A string that is either error or replace. This specifies how to handle cases where supplied certnames conflict with existing certnames stored in the node inventory connections database. If you specify error, the endpoint returns a 409 response if it finds any duplicate certnames. If you specify replace, the endpoint overwrites the existing certname with the new connection details if it finds a duplicate.

Here is an example of a complete request to the /command/create-connection endpoint that specifies and SSH connection:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/inventory/v1/command/create-connection"
data='{"certnames": [
           "sshnode1.example.com",
           "sshnode2.example.com"
        ], 
        "type": "ssh", 
        "parameters": {
            "port": 1234, 
            "connect-timeout": 90, 
            "user": "inknowahorse", 
            "run-as": "fred"
           },
        "sensitive_parameters": {
            "password": "password", 
            "sudo-password": "xtheowl"
         }, 
         "duplicates": "replace"
}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

SSH parameters and sensitive parameters

When the connection type is ssh, the following keys are available for the parameters object. Only the user key is required.

user

Required. A string naming the user to log in as when connecting to the host.

port

An integer defining the connection port.

Default: 22

connect-timeout

An integer specifying the length of time, in seconds, that you want PE to wait when establishing connections.

run-as

A string specifying the user name to use to run commands after logging in to the host.

Default: The same value as user.

tmpdir

A string specifying the directory to use to upload and execute temporary files on the target.

Specify this only if the temporary directory is different than /temp.

tty

A Boolean specifying whether to enable text terminal allocation.

hostname

A string specifying the hostname to connect to if it is different from the certname.

When the Puppet orchestrator targets a certname to run a task, it first considers the value of the hostname key present in the connection parameters, if supplied. If omitted, the certname is used as the hostname when the orchestrator connects to the host.

Do not specify a hostname when configuring multiple connections (multiple certnames) in the same request.

Only specify hostname if the node's certname in PE is different than the hostname of the intended target. In this case the certname in the request body must be the desired node certname, and the hostname in the parameters object must be the hostname to connect to.

When the connection type is ssh, the following keys are available for the sensitive-parameters object:

password

Conditionally required. A string specifying the password to use to authenticate the connection.

To form a valid request, you must specify either password or private-key-content.

private-key-content

Conditionally required. The contents of a private key, as a string.

To form a valid request, you must specify either password or private-key-content.

sudo-password

An optional string specifying the password to use when changing users via run-as.

Only include this if run-as is specified in the parameters object.

WinRM parameters and sensitive parameters

When the connection type is winrm, the following keys are available for the parameters object. Only the user key is required.

user

Required. A string naming the user to log in as when connecting to the host.

port

An integer defining the connection port.

Default: 22

connect-timeout

An integer specifying the length of time, in seconds, that you want PE to wait when establishing connections.

tmpdir

A string specifying the directory to use to upload and execute temporary files on the target.

Specify this only if the temporary directory is different than /temp.

extensions

An array listing file extensions that are allowed for tasks.

hostname

A string specifying the hostname to connect to if it is different from the certname.

When the Puppet orchestrator targets a certname to run a task, it first considers the value of the hostname key present in the connection parameters, if supplied. If omitted, the certname is used as the hostname when the orchestrator connects to the host.

Do not specify a hostname when configuring multiple connections (multiple certnames) in the same request.

Only specify hostname if the node's certname in PE is different than the hostname of the intended target. In this case the certname in the request body must be the desired node certname, and the hostname in the parameters object must be the hostname to connect to.

When the connection type is winrm, the sensitive-parameters object allows only one key, which is the password key. This key required and contains a string specifying the password to use to authenticate the connection.

Response format

If the request is well-formed, valid, and the entries are successfully recorded in the database, the server returns a 201 response with a JSON object containing the connection_id for each connection's record. For example:

{
  "connection_id": "3c4df64f-7609-4d31-9c2d-acfa52ed66ec"
}

The endpoint also inserts each of the provided certnames into PuppetDB with an empty fact set, if they are not already present. After certnames are added to PuppetDB, you can view them from the Nodes page in the Puppet Enterprise (PE) console. You can also add them to your inventory node lists when you set up jobs to run tasks.

Error responses

Error responses follow the usual format of Node inventory API errors.