×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

Unsupported content

 

This version of the product is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.
BMC Discovery 11.3 ... Administering Using command line utilities

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:

tw_vault_control [options]

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

tideway@DE-32 ~]$ tw_vault_control --user=system --password=MyPassword --open
Passphrase:					
Opening vault
[tideway@DE-32 ~]$ tw_vault_control --user=system --password=MyPassword --close
Closing vault
[tideway@DE-32 ~]$ tw_vault_control --user=system --set-passphrase
Password:
New Passphrase:
Verify New Passphrase:
** Passphrase set **
[tideway@DE-32 ~]$ tw_vault_control --user=system --password=MyPassword --open
Passphrase:					
Opening vault
[tideway@DE-32 ~]$ tw_vault_control --user=system --status
Password:
State      : OPEN
Passphrase : Set

Credential Counts
                Atrium CMDB : 0
          Cisco IMC Web API : 0
         EMC VPLEX REST API : 0
                File Export : 0
             HP iLO Web API : 0
                JDBC Export : 0
        Mainview z/OS Agent : 0
                       SNMP : 0
                        SQL : 3
                       WBEM : 0
                    Windows : 0
                     rlogin : 0
                        ssh : 1
                     telnet : 0
                    vCenter : 0
                    vSphere : 0
        ---------------------------
                      Total : 4
[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.

[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword 
		--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.

[tideway@DE-32 ~]$ tw_vault_control --user=system --password=MyPassword 
	--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.

[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword 
	--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:

[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword 
	--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:

[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword 
	--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.

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

[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword --show 
--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.

[tideway@appliance01 ~]$ tw_vault_control --user=system --password=MyPassword 
	--remove --id=36cb4e33b031148859047f0000014f31
[tideway@appliance01 ~]$
Was this page helpful? Yes No Submitting... Thank you
Last modified by Duncan Tweed on Jan 18, 2018
tw_vault_control command_line_utility

Comments

Log in or register to comment.

tw_cluster_control
tw_event_control
© Copyright 2004 - 2022 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.