wlpn-cli-collective

A wlpn plugin for registering collective members and host credentials with a Liberty Collective.

This plugin comes included with the wlpn cli.

npm install -g wlpn

Table of Contents

• Commands
  • Help
  • Register Host
    • Options
  • Update Host
    • Options
  • Unregister Host
    • Options
  • Join
    • Options
  • Remove
    • Options
• Environment Variables
  • WLPN_USER_DIR
  • DEBUG

Commands

Help

You can print help and general usage with this command: wlpn collective:help For help with a specific command, run wlpn collective:<cmd> [-h|--help]

Register Host

Registering a host on the collective will add a host machine to the collective. This includes the address at which to reach the host, and credentials for remotely logging into the host. Remote logins are performed over OpenSSH, so your host system must support OpenSSH logins.

To register your host with the collective, run wlpn collective:registerHost <hostname> [options..]

Whenever possible, you should use the fully-qualified domain name of the target host. This is because Liberty does not do anything special to validate domain names or resolvable addresses beyond what your operating system already does on your behalf. You can use other forms of addressing provided they are internally consistent, (like hostnames set over /etc/hosts) but it is not recommended.

Options

| Flag | ENV Variable | Description | |------|--------------|--------------------------------------| | --host=name | | Optional. The host name of the target Collective Controller. Defaults to localhost. | | --port=num | | Required. The HTTPS port number of the target Collective Controller. | | --user=name | | Required. An Administrator user for the target Collective Controller. | | --password=pwd | WLPN_ADMIN_PASSWORD | Required. The password for the Administrator user for the target Collective Controller. | | --autoAcceptCertificates | | Optional. Automatically trust SSL certificates during this command. | | --rpcHost=name | | Optional. The host on which the RPC or SSH mechanism is listening. Defaults to the hostName. | | --rpcPort=num | | Optional. The port on which the RPC or SSH mechanism is listening. Defaults to SSH port 22. | | --rpcUser=name | | Optional. The user with which to authenticate to the RPC or SSH mechanism. Defaults to the current OS user. | | --rpcUserPassword=pwd | WLPN_RPC_USER_PASSWORD | Optional. The password for the rpcUser. The default is to use SSH key authentication. Set this value if SSH is not supported for the host. Only one authentication option (rpcUserPassword or sshPrivateKey) should be used, but not both. | --sshPrivateKey=path | | Optional. The path to the SSH key to use to authenticate to the host. Defaults to a newly generated SSH key. Only one authentication option (rpcUserPassword or sshPrivateKey) should be used, but not both. | | --sshPrivateKeyPassword=keypass | WLPN_SSH_PRIVATE_KEY_PASSWORD | Optional. Password for supplied SSH Private Key. |

Update Host

Updating a host is done with the same parameters as a Register Host command. To update a host on the collective, run wlpn collective:updateHost <hostname> [options..]

Options

The options available are identical to register host's options.

Unregister Host

Unregister host is the opposite operation of register host. This will remove the host machine from the collective.

Note: You cannot run unregister host if there are one or more applications joined to the collective on this host. You must first run the remove command on all joined applications.

Options

| Flag | ENV Variable | Description | |------|--------------|--------------------------------------| | --host=name | | Optional. The host name of the target Collective Controller. Defaults to localhost. | | --port=num | | Required. The HTTPS port number of the target Collective Controller. | | --user=name | | Required. An Administrator user for the target Collective Controller. | | --password=pwd | WLPN_ADMIN_PASSWORD | Required. The password for the Administrator user for the target Collective Controller. | | --autoAcceptCertificates | | Optional. Automatically trust SSL certificates during this command. |

Join

Once your host has been registered with the collective, you can add application instances via the join command. Joining an application requires that the host machine be registered with the collective first.

To join an app to the collective, run wlpn collective:join <appName> [options..]

The <appName> will be the name of the application directory found within the $WLPN_USER_DIR directory.

This will download a set of key materials from the collective, and place them in the $WLPN_USER_DIR/<appName> folder, as well as creating a join.json file that contains information about the collective.

Options

| Flag | ENV Variable | Description | |------|--------------|--------------------------------------| | --host=name | | Optional. The host name of the target Collective Controller. Defaults to localhost. | | --port=num | | Required. The HTTPS port number of the target Collective Controller. | --user=name | | Required. An Administrator user for the target Collective Controller. | --password=pwd | WLPN_ADMIN_PASSWORD | Required. The password for the Administrator user for the target Collective Controller. | --autoAcceptCertificates | | Optional. Automatically trust SSL certificates during this command. | --keystorePassword=pwd | WLPN_KEYSTORE_PASSWORD | Required. The password to use for the generated serverIdentity.pfx. | --serverIdentityCertificateValidity=days | | Optional. Number of days the server identity certificate is valid. Default validity period is 5 years. Minimum validity period is 365. | --hostName=name | | Optional. Specify the hostName to use for this system. This only needs to be set when the system has multiple host names or does not have its host name configured. | | --genDeployVars | | Optional. Retrieves automatically generated deploy variables from the collective controller and saves them into the app's collective configuration. | --sudoUser=name | | Optional. The user to sudo to perform the remote operation. This requires that the target system supports sudo. By default, sudo is not used. Setting this property implies useSudo=true. | | --sudoUserPassword=pwd | WLPN_SUDO_USER_PASSWORD | Optional. The password for the specified sudo user key. | | --useSudo=bool | | Optional. Indicates sudo should be used to perform the remote operation. This requires that the target system supports sudo. By default, sudo is not used. If sudo is used, the sudoUser must be provided. | | --clusterName=name | | Optional. Name of cluster for member to join when joining controller. |

Remove

Remove is the opposite operation of join. This will remove the app from the collective, delete the key materials downloaded from the collective, and remove the join.json file.

Options

| Flag | ENV Variable | Description | |------|--------------|--------------------------------------| | --host=name | | Optional. The host name of the target Collective Controller. Defaults to localhost. | | --port=num | | Required. The HTTPS port number of the target Collective Controller. | --user=name | | Required. An Administrator user for the target Collective Controller. | | --password=pwd | WLPN_ADMIN_PASSWORD | Required. The password for the Administrator user for the target Collective Controller. | | --autoAcceptCertificates | | Optional. Automatically trust SSL certificates during this command. | | --hostName=name | | Optional. Specify the hostName to use for this system. This only needs to be set when the system has multiple host names or does not have its host name configured. |

Environment Variables

There are some environment variables you can set before calling wlpn-cli-collective commands.

WLPN_USER_DIR

The WLPN_USER_DIR defaults to $HOME/wlpn, and is where all of your application instance folders reside.

DEBUG

This plugin use of the debug library, and thus, you can retrieve debug output during the application run. All of the debug output this module generates is prefixed with the wlpn-cli-collective: prefix. Examples: All wlpn-cli-collective messages:

$ DEBUG=wlpn-cli-collective:* wlpn collective:join my-app [options..]

All debug messages:

$ DEBUG=* wlpn collective:join my-app [options..]

NOTE: We STRONGLY advise against using this option in production; you should never log debug output in this way if your application handles sensitive data.