Password Manager
The Password Manager is a command line tool that assists in configuring or maintaining the security mechanism of Orchestra (see chapter Security). One of its main functions is to set a custom master password for the first time, thereby enhancing security.
Start Scripts
The Password Manager can be executed using the provided start scripts. Depending on your operating system, choose one of the following:
Orchestra/Startscripts/Unix/pwd_manager.shOrchestra/Startscripts/Windows/pwd_manager.cmd
Interactive Mode
When the start scripts are executed without any arguments, the Password Manager starts in interactive mode. In this mode, the manager remains open, allowing you to interact with it until you enter the command exit, or terminate it using CTRL+C.
Example:
Here we are executing the Password Manager in interactive mode.
Then we execute the check command with the default encryption
and an environment_settings.xml file located outside the Orchestra folder:
./pwd_manager.sh
> check -d -e /tmp/environment_settings.xml
Batch Mode
Batch mode is activated when the start script is launched with additional arguments. These arguments are the same as those used in interactive mode.
Example:
Here we execute the check command with the default encryption and an
environment_settings.xml file located outside the Orchestra folder:
./pwd_manager.sh check -d -e /tmp/environment_settings.xml
User Commands
The command set is designed for normal Orchestra users (administrators). All common use cases can be handled with these commands unless you have a specific Orchestra installation or are in need of state repair.
wizard
Guides you through the entire process of setting or changing the master password for your Orchestra installation. This includes generating a master secret, which must be provided to Orchestra at startup, encrypting the database username and password in the environment_settings.xml, and encrypting sensitive data in your runtime database.
Optional Switches:
-c, --case <number> the number of the use case:
0 = set master password
1 = change master password
2 = reset master password
-m, --master <password> the current master password
-s, --secret <secret> the current master secret
-e, --environment <filepath> the path to the 'environment_settings.xml'
-n, --newmaster <password> the new master password
--debug prints more details about the checks
Example:
wizard -e /home/dev/environment_settings.xml
wizard --environment /home/dev/environment_settings.xml
wizard -m mynewmasterpassword
check
Checks the encryption consistency of your Orchestra installation. This command verifies if the master secret, database username in the environment_settings.xml, database user password in the environment_settings.xml, and the encrypted sensitive data in the runtime database can be decrypted with the provided master password. This check is also performed by the wizard command before any changes are made.
Optional Switches:
-d, --default uses the default master password (must not
be used with -m and -s)
-m, --master <password> the custom master password (must not
be used with -d)
-s, --secret <secret> the secret for the given master password (must
not be used with -d)
-e, --environment <filepath> the path to the 'environment_settings.xml'
--debug prints more details about the checks
Example:
check -d
check -d -e /tmp/environment_settings.xml
check -m alohomora -s onnoBYT9x8Z0TnzaEdWufp1muXUGW45nDj/8OjVKEDwd2Hg= -e /tmp/environment_settings.xml
exit
Exits the Password Manager.
Example:
exit
help
Displays a help screen containing a list of all available commands along with detailed descriptions.
Optional Switches:
-e, --expert also prints expert commands
Example:
help
help -e
help --expert
Expert Commands
The expert commands are additional commands that should only be utilized by experienced Orchestra administrators or Orchestra support personnel.
Caution: There is a high risk of resulting in a broken or inconsistent installation if you do not know exactly what you are doing.
generate-secret
Generates a master secret from the provided master password. This master secret is an encrypted representation of the master password and must be provided to Orchestra at startup via a Java property.
This can be achieved, for example, by adding the property to Tomcat's setenv.sh/setenv.bat, or if Tomcat is running as a service, through the service manager GUI of Tomcat (see chapter Security).
Optional Switches:
-s, --store <filepath> the filepath where the generated secret should be saved
-m, --master <password> the custom master password for encryption
Example:
generate-secret -s /tmp/secret.key
generate-secret -m alohomora -s /tmp/secret.key
encrypt
Encrypts any given text with a master password. If the master password is left empty, the default one will be used for encryption (as was done in older Orchestra versions).
This command is typically used to encrypt the runtime database username and password before storing them in the environment_settings.xml of Orchestra. Remember that the master password for this encryption must match the one used for generating the master secret.
Optional Switches:
-d, --default uses the default master password for encryption (must
not be used with -m)
-m, --master <password> the custom master password for encryption (must not
be used with -d)
-t, --text <text> the text to be encrypted
Example:
encrypt
encrypt -d
encrypt --default --text ORCHESTRA
encrypt --master alohomora --text ORCHESTRA
upgrade-db
Caution: This command is executed against your Runtime Database.**
Upgrades the runtime database from the old security system to the new one. This command must only be executed once and does not require any further actions.
Optional Switches:
-e, --environment <filepath> the path to the 'environment_settings.xml'
--debug prints more details during execution
Example:
upgrade-db -e /tmp/environment_settings.xml
upgrade-db --environment /tmp/environment_settings.xml
change-masterpwd
This command is executed against your Runtime Database.
Decrypts all credentials stored in the runtime database with the old master password and re-encrypts everything with the new master password. If either of the entered master passwords is empty, it will be replaced with the default one.
Optional Switches:
-e, --environment <filepath> the path to the 'environment_settings.xml'
--debug prints more details about the checks
Example:
change-masterpwd -e /tmp/environment_settings.xml