tw_vault_control
The tw_vault_control utility enables you to control credential vault operations and perform credential updates from the command line. As all of this functionality is available through the UI, the utility is primarily intended to be used as a means of automating certain credential related procedures rather than an all purpose credential manager.
To use the utility, type the following command:
where options are any of the options described in the following table and the common command line options described in Using command line utilities.
Command Line Option | Description |
---|---|
--add filename | Add a new credential. Specify the credential details in a JSON formatted file. |
--change-passphrase | Change vault passphrase. You are prompted for the existing vault passphrase, then a new vault passphrase, and then confirmation of the new vault passphrase. |
--clear-passphrase | Clear the current vault passphrase. You are prompted for the existing vault passphrase. |
--close | Close the credential vault. |
--credpass | Set the password for a specified credential. |
--id=ARG | Specify a credential ID. Use with the show, remove, and credpass (set a credential password) options. |
--json | Specify JSON formatted output for the credential details. Use with the show option. |
--open | Open the credential vault. You are prompted for the vault passphrase. If no passphrase is set, press Enter. |
--passphrase=ARG | Specify the credential vault passphrase. Used to perform operations when the credential vault is closed. |
--quiet | Do not show informational messages. |
--remove | Remove a specified credential. The credential is specified using the id option. |
--set-passphrase | Set a vault passphrase. You are prompted for the new vault passphrase, and then confirmation. |
--show | Show the details of a specified credential or credentialse. The credential is specified using the id option. If no credential is specified, the details of all credentials are shown. |
--status | Show a status report containing the credential vault state (open or closed), whether or not a passphrase is set, and a count of the supported credential types. |
--type=ARG | Show credentials of a specified type. A list of supported credential types is available using the types option. |
--types | List supported credential types. |
--update | Update a credential using a specified JSON formatted file. |
User examples
This section shows a number of user examples.
Vault operations
The following output shows various vault operations, open, close, change passphrase and so on.
Passphrase:
Opening vault
[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword --close
Closing vault
[tideway@appliance01 ~]$ tw_vault_control --user=system --set-passphrase
Password:
New Passphrase:
Verify New Passphrase:
** Passphrase set **
[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword --open
Passphrase:
Opening vault
[tideway@appliance01 ~]$ tw_vault_control --user=system --status
Password for BMC Discovery UI user system:
State : OPEN
Passphrase : Unset
Credential Counts
AVI Vantage Web API : 0
Active Directory : 1
Amazon Web Services : 2
BeyondTrust Password Safe : 0
CMDB : 0
Centrify Identity Platform Server : 0
Cisco APIC REST API : 0
Cisco IMC Web API : 0
Citrix NetScaler NITRO REST API : 0
Control-M Web API : 0
CyberArk Credential Provider : 0
Dell EMC ScaleIO REST API : 0
EMC ECS Web API : 0
EMC VPLEX REST API : 0
File Export : 0
Google Cloud Platform : 0
HDI REST API : 0
HP iLO Web API : 0
IBM Db2 : 0
Ingres : 0
JDBC Export : 0
Mainframe z/OS Agent : 7
Microsoft Azure : 2
Microsoft SQL Server : 1
MySQL : 0
Nimble Storage Web API : 0
OpenStack : 0
Oracle : 0
Other Database : 0
PostgreSQL : 0
REST API with OAuth2 authentication : 0
REST API with basic authentication : 0
REST API with digest authentication : 0
SNMP : 22
SQL : 0
Sybase : 0
Thycotic Secret Server : 0
WBEM : 1
Windows : 20
rlogin : 11
ssh : 58
telnet : 17
vCenter : 8
vSphere : 20
vSphere Web API : 0
-------------------------------------------
Total : 142
[tideway@appliance01 ~]$
View credential details
In the following example, the first line after the command shows the credential ID. The example shows the details of ssh credentials.
--show --type=ssh
36cb4e33b031160408b47f0000014f31
description = 'dummy'
enabled = True
internal.created = 1454894868.166026
internal.messages = []
internal.modified = 1454894868.166026
internal.valid = True
ip_range = '0.0.0.0/0,::/0'
label = 'dummy'
password = '*MASKED*'
range_prefixes = []
shell.force_subshell = False
shell.prompt = '[#>%$]'
shell.record = False
ssh.key.data = '*MASKED*'
ssh.key.passphrase = '*MASKED*'
ssh.key.set = False
ssh.port = 22
ssh.prefauth = ['password', 'keyboard-interactive']
ssh.timeout = 180.0
su.enabled = False
su.password = '*MASKED*'
su.username = 'root'
types = ['ssh']
username = 'dummy'
Total credentials = 1
[tideway@appliance01 ~]$
You can specify a particular credential by ID using --id=_credentialID_ rather than --type=_type_. The output of the show option shows the format of files for adding credentials. You can also use json. The following example shows credential details in normal output and as JSON formatted output.
--show --id=36cb4e33b031160408b47f0000014f31
36cb4e33b031160408b47f0000014f31
description = 'dummy'
enabled = True
internal.created = 1454894868.166026
internal.messages = []
internal.modified = 1454946801.590793
internal.valid = True
ip_range = '0.0.0.0/0,::/0'
label = 'dummy'
password = '*MASKED*'
range_prefixes = []
shell.force_subshell = False
shell.prompt = '[#>%$]'
shell.record = False
ssh.key.data = '*MASKED*'
ssh.key.passphrase = '*MASKED*'
ssh.key.set = False
ssh.port = 22
ssh.prefauth = ['password', 'keyboard-interactive']
ssh.timeout = 180.0
su.enabled = False
su.password = '*MASKED*'
su.username = 'root'
types = ['ssh']
username = 'dummy'
[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword
--show --id=36cb4e33b031160408b47f0000014f31 --json
{"su.enabled":false,"shell.force_subshell":false,"ip_range":"0.0.0.0/0,::/0",
"internal.modified":1454946801.590793,"description":"dummy",
"uuid":"36cb4e33b031160408b47f0000014f31","shell.record":false,
"shell.prompt":"[#>%$]","label":"dummy","ssh.port":22,
"ssh.timeout":180.000000,"username":"dummy",
"ssh.prefauth":["password","keyboard-interactive"],
"ssh.key.passphrase":"*MASKED*","range_prefixes":[],
"internal.valid":true,"internal.messages":[],"ssh.key.set":false,
"su.password":"*MASKED*","password":"*MASKED*","types":["ssh"],
"internal.created":1454894868.166026,"ssh.key.data":"*MASKED*",
"enabled":true,"su.username":"root"}
[tideway@appliance01 ~]$
Adding a credential
To add a credential, jcreate a JSON formatted file with the required credential parameters. The simplest way of doing this is to use the {{show}} option to create a file from an existing credential of the same type.
--show --id=36cb4e33b031160408b47f0000014f31 --json > credential.json
[tideway@appliance01 ~]$
All sensitive data is masked, and must be edited before the credential can be updated. Failure to do so results in errors of the following type:
- ERROR: The password value is masked
- ERROR: The ssh.key.data value is masked
- ERROR: The ssh.key.passphrase value is masked
- ERROR: The su.password value is masked
These errors need to be corrected before the credential can be added. The file in the example has been edited for readability:
"su.enabled":false,
"shell.force_subshell":false,
"ip_range":"0.0.0.0/0,::/0",
"label":"dummy",
"ssh.prefauth":["password","keyboard-interactive"],
"shell.record":false,
"shell.prompt":"[#>%$]",
"ssh.port":22,
"ssh.timeout":180.000000,
"username":"dummy42",
"description":"A dummy",
"ssh.key.passphrase":"",
"range_prefixes":[],
"internal.valid":true,
"internal.messages":[],
"ssh.key.set":false,
"su.password":"thisisadummypassword",
"password":"thisisadummypassword",
"types":["ssh"],
"ssh.key.data":"",
"enabled":true,
"su.username":"root"
}
Create the credential using the add option:
--add credential.json
Loading credential.json
9e7d6a33b0d7937854fc89485ed5075d
description = 'A dummy'
enabled = True
internal.created = 1454966375.104274
internal.messages = []
internal.modified = 1454966375.104274
internal.valid = True
ip_range = '0.0.0.0/0,::/0'
label = 'dummy'
password = '*MASKED*'
range_prefixes = []
shell.force_subshell = False
shell.prompt = '[#>%$]'
shell.record = False
ssh.key.data = '*MASKED*'
ssh.key.passphrase = '*MASKED*'
ssh.key.set = False
ssh.port = 22
ssh.prefauth = ['password', 'keyboard-interactive']
ssh.timeout = 180.0
su.enabled = False
su.password = '*MASKED*'
su.username = 'root'
types = ['ssh']
username = 'dummy42'
[tideway@appliance01 ~]$
Changing a credential password
This example shows changing a password for a credential:
--id=36cb4e33b031160408b47f0000014f31 --credpass
New Password:
Verify New Password:
** Password updated **
[tideway@appliance01 ~]$
Updating a credential
The simplest way to update a credential is to dump the credential to a JSON formatted file (--json), edit the file and use that to update. As with adding a credential, all sensitive data is masked, and must be edited before the credential can be updated. Failure to do so results in the same type of errors as for adding a credential and need to be corrected before the credential can be added.
--show --id=36cb4e33b031160408b47f0000014f31 --json
{"su.enabled":false,"shell.force_subshell":false,"ip_range":"0.0.0.0/0,::/0",
"internal.modified":1454946801.590793,"description":"dummy",
"uuid":"36cb4e33b031160408b47f0000014f31","shell.record":false,"shell.prompt":"[#>%$]",
"label":"dummy","ssh.port":22,"ssh.timeout":180.000000,"username":"dummy",
"ssh.prefauth":["password","keyboard-interactive"],"ssh.key.passphrase":"*MASKED*",
"range_prefixes":[],"internal.valid":true,"internal.messages":[],"ssh.key.set":false,
"su.password":"*MASKED*","password":"*MASKED*","types":["ssh"],
"internal.created":1454894868.166026,"ssh.key.data":"*MASKED*","enabled":true,
"su.username":"root"}
[tideway@appliance01 ~]tw_vault_control --user=system --password=MyPassword
--show --id=36cb4e33b031160408b47f0000014f31 --json > cred99.json
Edit the credential file, ensuring that any data that has been replaced with *MASKED* is either replaced with correct data, or an empty string (for example "ssh.key.data":"", where ssh key exchange is not configured.
--id=36cb4e33b031160408b47f0000014f31 --json > cred99.json
[tideway@appliance01 ~]$ vi cred99.json
[tideway@appliance01 ~]$ tw_vault_control --user=system
--password=MyPassword --update --id=36cb4e33b031160408b47f0000014f31 cred99.json
36cb4e33b031160408b47f0000014f31
description = 'dummy'
enabled = true
internal.created = 1454894868.166026
internal.messages = []
internal.modified = 1454946801.590793
internal.valid = true
ip_range = '0.0.0.0/0::/0'
keyboard-interactive']
label = 'dummy'
password = '*MASKED*'
range_prefixes = []
shell.force_subshell = false
shell.prompt = '[#>%$]'
shell.record = false
ssh.key.data = '*MASKED*'
ssh.key.passphrase = '*MASKED*'
ssh.key.set = false
ssh.port = 22
ssh.prefauth = ['password'
ssh.timeout = 180.000000
su.enabled = false
su.password = '*MASKED*'
su.username = 'root'
types = ['ssh']
username = 'dummy'
[tideway@appliance01 ~]$
Deleting (removing) a credential
This example shows the removal of a credential. The credential is specified by ID.
--remove --id=36cb4e33b031148859047f0000014f31
[tideway@appliance01 ~]$