Command-Line Updates to Password Manager

FlexNet Manager Suite 2021 R1 (On-Premises)

The mgspswd command-line utility allows rapid updating of the Password Manager on an individual inventory beacon. It is installed on each inventory beacon in InstallDir\RemoteExecution (by default C:\Program Files\Flexera Software\Inventory Beacon\RemoteExecution\mgspswd.exe). It is an alternative to the GUI presentation of the Password Manager.

This utility supports either:
  • Storing credentials in a local vault (encrypted within the Windows registry), and recalling them on demand from there
  • Storing a query string that can uniquely access one existing credential saved in a CyberArk Vault, where integration with CyberArk has been detected (by the presence of the CyberArk Credential Provider installed on the inventory beacon). In this case, you may switch between storage types for individual credentials: for example, you can reference CyberArk for production passwords, but use the FlexNet Beacon vault to store credentials for test environments that have lower administrative overheads.
      mgspswd.exe --add logical-name [options...] 
      mgspswd.exe --delete logical-name
      mgspswd.exe --help
      mgspswd.exe --list [logical-name]
      mgspswd.exe --matches [options...] 
      mgspswd.exe --recrypt
      mgspswd.exe --reset

where logical-name is the friendly name given to the current credential (name/password pair).

For some credential types, certain parameters can be specified in alternate ways. Parameters for which this occurs are:
  • Domain: the Windows domain within which the specified credential applies. This is not available as a separate parameter in the command line. You may insert the domain into the account name parameter, using the normal format of domainName\sampleUser.
  • Password: while this value can be provided in the command line, it will be visible there in plain text. If omitted as a command-line parameter, it can be entered interactively, in which case the password characters are masked.
  • Other mandatory parameters (such as account and the logical name, when saving to the FlexNet Beacon vault) also prompt interactively for values if they are omitted from the command line.

The parameters and options available in the command line include the following (in alphabetical order):

Options Notes
--account account-name Specify the account name (often called the user name) to use. This parameter is only used with the ‑‑add parameter, and only when --vault is not specified as CyberArk.
In its simplest form, this parameter specifies only the account name (or user name). Three compound formats are also supported:
  • To specify a domain account within a particular domain (including for an account that is --type WindowsDomain), you may identify the domain using the common backslash-separated format, such as domainName\sampleUser.
  • To specify the sampleUser account name for Windows computers that are not part of a domain, use the string literal "localhost" by entering localhost\sampleUser.
  • You can include the string variable $(MachineName) as part of the account name (followed by a backslash separator). At run-time, the name of the computer on which remote execution is being performed will replace $(MachineName). For example:
    --account $(MachineName)\Administrator
--add logical-name [options...] Add a new credential (account/password pair) with the specified logical name, account name, and password.
  • If you repeat the command line with the --add parameter and a logical-name that already exists in Password Manager, the existing record is updated.
  • If you omit the account name or password parameters, and they are required, the utility prompts for the missing parameters. (Be aware for Oracle listener access, only a password is required and is mandatory, and there is no account name.)
Tip: If the logical name includes spaces, enclose it in double quotation marks.
Example:
mgspswd --add "Local admin account" --account $(MachineName)\Administrator
Since the --password option is omitted, the utility prompts for the password value, masking the characters as they are entered. This example presumes the unusual situation of using a common administrator password across a range of devices. A more common example might specify an exact match for a particular device name, such as:
mgspswd --add "myDevice admin" --account myDevice\Administrator
Note: When the parameter --vault CyberArk is included in the command line, the command is adding to Password Manager a reference to an existing credential saved in an appropriate CyberArk vault and safe. Commands from the inventory beacon cannot change the content of CyberArk. The saved reference allows Password Manager to request the appropriate credential from CyberArk at an appropriate time.
--cyberark-query ["]query-string["]

This parameter is only used with the ‑‑add parameter, and only when the parameter --vault CyberArk is included in the command line. Specify the exact query string expected by CyberArk for it to return the required credential. Of course, the credential itself (account name and password pair) must already exist in the appropriate CyberArk vault and safe (the vault is specified when CyberArk integration is first configured, and the safe may optionally be specified as part of the query string). If the query string contains any white space, it should be enclosed in double quotation marks (otherwise, these are optional). Details of the query string are specific to your implementation of CyberArk, and must be obtained from your CyberArk administrator. (See also privilege-cyberark-query.)
--delete logical name Removes the credential (account and password record) with the specified logical name from Password Manager. Notice that when the vault setting is for the default (omitted, or set to FlexNetBeacon), the credentials themselves are removed from the FlexNet Beacon vault; but when the parameter --vault CyberArk is included in the command line, the reference to the CyberArk record (including the query string) is removed, but the credential itself (account name and password pair) is not removed from CyberArk. Removal of credentials from CyberArk must be performed by a CyberArk administrator.
--filter-dnsdomains list

If this credential should only be used for a limited set of target devices, you can specify the DNS domains of affected managed devices here as a comma-separated list of domain names. If multiple filters are specified, target devices that match any of the specified criteria will use the credentials. Credentials matched through a filter are tried before unfiltered credentials.

This option is only used with the --add or --match parameters.
--filter-dnsnames list

If this credential should only be used for a limited set of target devices, you can specify the DNS names of target devices as a comma-separated list of names. If multiple filters are specified, target devices that match any of the specified criteria will use the credentials. Credentials matched through a filter are tried before unfiltered credentials.

This option is only used with the --add or --match parameters.
--filter-ipaddresses list

If this credential should only be used for a limited set of target devices, you can specify the IPv4 addresses of target devices as a comma-separated list of addresses. If multiple filters are specified, target devices that match any of the specified criteria will use the credentials. Credentials matched through a filter are tried before unfiltered credentials.

This option is only used with the --add or --match parameters.
--filter-macaddresses list
If this credential should only be used for a limited set of target devices, you can specify the MAC addresses of target devices as a comma-separated list of addresses. Both the Windows and UNIX formats are valid. Example:
00:01:b0:c4:e6:10,00-AF-F7-CD-F9-10
If multiple filters are specified, target devices that match any of the specified criteria will use the credentials. Credentials matched through a filter are tried before unfiltered credentials.

This option is only used with the --add or --match parameters.
--filter-names list
If this credential should only be used for a limited set of target devices, you can specify the device names of target devices here as a comma-separated list. For example: 
accounts-laptop,finance-desktop

If multiple filters are specified, target devices that match any of the specified criteria will use the credentials. Credentials matched through a filter are tried before unfiltered credentials.

This option is only used with the --add or --match parameters.
--filter-netbiosdomains list

If this credential should only be used for a limited set of target devices, you can specify the NetBIOS domain names of target devices as a comma-separated list of domain names. If multiple filters are specified, target devices that match any of the specified criteria will use the credentials. Credentials matched through a filter are tried before unfiltered credentials.

This option is only used with the --add or --match parameters.
--filter-oracleservicenames list
This parameter only applies to accounts of type OracleDatabase. If this credential should only be used for a limited set of target devices, you can specify a comma-separated list of the Oracle service names to which the credential applies. Use only with the OracleDatabase and OracleListener account types. For example, 
ORA001,TestORA

If multiple filters are specified, target devices that match any of the specified criteria will use the credentials. Credentials matched through a filter are tried before unfiltered credentials.

This option is only used with the --add or --match parameters.

Tip: Oracle names may match on individual parts of the service name. It may be helpful to specify the fully qualified service name in the Oracle service names filter to avoid unintentional matches. To use a filter to match service names with multiple suffixes, you can specify each fully qualified service name in the filter, separated by commas.
--help Displays a list of parameters.
--list Lists all credentials within the password store. All elements are shown (logical name, account name, and password) with the password displayed in masking characters.

If the optional logical-name for a credential is supplied, the utility displays the credential with the specified logical name.
--matches
Identifies all the credentials in the Password Manager that match (and therefore may be applied to) a device. To narrow the specification, you may add the --type option with one valid value, and any of the filter options (also described in this listing):
  • --filter-names
  • --filter-dnsnames
  • --filter-dnsdomains
  • --filter-netbiosdomains
  • --filter-ipaddresses
  • --filter-macaddresses
  • --filter-oracleservicenames.
--password password

Specify the password to use. Only permitted for the default FlexNet Beacon vault (that is, omit when --vault CyberArk is specified).

Note that if you do not wish to see the password echoed in plain text on the command line, you may omit this parameter, and the utility will prompt for it, and mask it as it is entered.

Passwords are required for the OracleListener account type, and are optional for all other account types.

This option is only used with the --add parameter.
--privatekeyfile path

The name and location of a source file containing the private key for SSH, for use with the default FlexNet Beacon vault. (This parameter is not relevant when --vault CyberArk, since CyberArk then owns management of the public/private key pair, and simply returns the private key on demand through the appropriate query string.)

Using the default FlexNet Beacon vault, the private key file is read from the specified path, and added to the Password Manager. The private key can be in the OpenSSH project’s format (generated using ssh-keygen ) or the PuTTY format (generated using PuTTYgen.exe).

The corresponding public key must be in place on the target device before SSH login using a private-public key pair. If you are using OpenSSH on target devices, the public key is expected in ~/.ssh/authorized_keys. Use mgspswd.exe --list logical-name to obtain the public key to add to ~/.ssh/authorized_keys. Other SSH implementations may require that the public key be stored elsewhere.

This option is only used:
  • With the --add parameter
  • For the SSHKeyPair type of credential
  • When the vault is not CyberArk.
--privilege-cyberark-query ["]query-string["]

Specify the exact query string expected by CyberArk for it to return the credential required to escalate privileges on the target device. Of course, the escalation credential itself (account name and password pair) must already exist as a separate credential in the appropriate CyberArk vault and safe. If the query string contains any white space, it should be enclosed in double quotation marks (otherwise, these are optional). (See also cyberark-query.)

This option is only used:
  • With the --add parameter
  • When the parameter --vault CyberArk is included in the command line
  • For the SSHPassword or SSHKeyPair types of credential.
--privilege-password password
You can specify that login should be attempted with elevated privileges on target devices running UNIX-like operating systems. This is the password used to gain those elevated (root) privileges. (See also --privilege-password-prompt and privilege-prefix, which are used in conjunction with this.)
Tip: If sudo on the target device(s) is configured to allow escalation of privileges without requiring an interactive password, just omit this parameter.
This option is only used:
  • With the --add parameter
  • For the SSHPassword or SSHKeyPair types of credential
  • When the vault is not CyberArk.
--privilege-password-prompt text

For UNIX-like devices on which login should be attempted using elevated privileges, specify the exact prompt for which FlexNet Beacon should wait before issuing the value of the --privilege-password parameter.

Tip: The sudo tool typically issues a prompt similar to this:
[sudo] password for userName:
You could enter this entire value, since you know the User name for this login, in the --privilege-password-prompt parameter; but (assuming that this credential is reused across multiple servers) this approach is at risk because of variations across different versions of UNIX-like operating systems. A risk-free alternative is to use the following special settings:
  1. Supply the elevation command with an option to declare a specialized password: 
    --privilege-prefix "sudo -p flxpwd:"
    The -p option instructs sudo to issue the specified prompt (for a password) when it is invoked by the FlexNet Beacon engine.
  2. for this parameter, enter
    --privilege-password-prompt "flxpwd:"
    (or exactly the prompt value you specified in the field described above).
  3. Be sure to also specify the --privilege-password password parameter.
When invoked by the FlexNet Beacon engine, sudo now issues a known prompt, which in turn is recognized by the FlexNet Beacon engine, and inventory collection can proceed.
This --privilege-password-prompt option is only used:
  • With the --add parameter
  • For the SSHPassword or SSHKeyPair types of credential
  • When the vault is not CyberArk.
--privilege-prefix prefix

For UNIX-like devices on which login should be attempted using elevated privileges, specify the valid privilege elevation command (such as sudo or priv) here. This option is ignored if the credential matches any Windows devices.

This option is only used:
  • With the --add parameter
  • For the SSHPassword or SSHKeyPair types of credential
  • When the vault is not CyberArk.
--recrypt Decrypts all passwords in the Password Manager vault using the current primary password (security key), replaces the primary password with a new one, and re-encrypts all the passwords in the Password Manager vault with the new security key, using the strongest available algorithm. For more information, see Password Manager Security Overview.
--reset Clears the Password Manager vault on this inventory beacon, and resets the internal security key.
--type type The credential type. This must be one of:
  • OracleDatabase: to connect to an Oracle Database instance
  • OracleListener: to connect to a server running Oracle listener services (for this type, a password is mandatory and no account name can be defined)
  • OracleVMManagerApiAccess: an account that can access the API for Oracle VM Manager
  • SSHKeyPair: to connect to managed devices using SSH, when SSH on the target devices is configured to require a key-value pair for login
  • SSHPassword: to connect to managed devices using SSH, when SSH on the target devices is configured to require a password for login
  • VMwareESX: to connect to a VMware ESX server
  • VMwareVirtualCenter: to connect to a VMware Virtual Center server
  • WindowsDomain: when tasks being remotely executed on Windows devices should run as a domain user
  • WindowsLocal: when tasks being remotely executed on Windows devices should run as a local computer user.
This option is only used with the --add or --matches parameters.
--vault vault-type
The kind of vault used for storing the credentials. May be omitted when CyberArk integration has not been detected on this inventory beacon (in which case the FlexNet Beacon vault is used). When CyberArk is available, the vault-type must be one of:
  • CyberArk (the normal choice in a production environment where CyberArk has been detected)
  • FlexNetBeacon (note: no white space).
Tip: Values are case insensitive.
This option is only used with the --add or --matches parameters.
Example 1: Set a new record to retrieve the credential for a Windows domain (account and password) saved in CyberArk (this command is entered all on one line):
mgspswd --add WDomain07 --vault CyberArk --type WindowsDomain 
--cyberark-query Safe=PasswordSafe;Folder=Root\Applications;Object=WinDomain07-DLPW
Because the domain name is a property of the credential returned from CyberArk, no specification of the domain is needed in this command line, and you rely on naming conventions in the logical-name to track the purpose of this credential.
Example 2: Specify the same credential saved in the FlexNet Beacon vault (when CyberArk integration has not been detected on this inventory beacon):
mgspswd --add WDomain07 --type WindowsDomain --account ourDomain\winSvcAcct --password qwerty1
Notice that you cannot specify the domain name as a distinct command line parameter, but you can specify it as part of the account data as shown. You may choose to enter the password interactively (with character masking) by omitting it from the command line.
Example 3: Using the default FlexNet Beacon vault (when CyberArk integration has not been detected on this inventory beacon), save a local account on a target device named myDevice:
mgspswd --add myDevicePW --type WindowsLocal --account svcUser --password qwerty! 
--filter-names myDevice
Each call to mgspswd with the --add parameter (and using the default vault) stores on the inventory beacon:
  • A logical name for the account/password pair (when this is a new logical name, a new entry is created; and when it is an existing logical name, the current entry is updated)
  • Optional filters to restrict the use of this credential to specific target devices (in this example, the filter-names parameter ensures that this credential is attempted only on the device of the matching device name)
  • An account name (or username) on the target device
  • The account password on the target device, encrypted using a private key unique to each inventory beacon, with the private key stored as a private data object on the inventory beacon. The private key is automatically initialized with the first save to the Password Manager on each inventory beacon.
Example 4: Register the same local credentials, saved in CyberArk, for use on the target device named myDevice:
mgspswd --add myDevicePW --type WindowsLocal --filter-names myDevice --vault CyberArk
--cyberark-query Safe=PasswordSafe;Folder=Root\Applications;Object=LocPW-myDevice
In this case, the account name (username) and password are already saved within CyberArk, and we supply the query string that returns this credential for use. Notice that the same filter now means that the inventory beacon only attempts to retrieve this credential from CyberArk when it is targeting the matching device.

Notes

Tip: For Windows-based computers, use net use \\machineName\ipc$ to test that login credentials work before adding them to Password Manager.

FlexNet Manager Suite (On-Premises)

2021 R1