wlpn-cli-collective v2.5.2
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 wlpnTable of Contents
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.