Enportal/5.5/admin/system administration/CLI utilities: Difference between revisions

imported>Mike.berman
No edit summary
 
imported>Jason.nicholls
 
(7 intermediate revisions by 2 users not shown)
Line 39: Line 39:
|-
|-
|service
|service
|Manages a Windows system service that will automatically start enPortal when the server is started.  <br><br> <tt>service install</tt> - Creates a new service <br> <tt>service remove</tt> - Deletes the existing service <br> <tt>service start</tt> - Starts the service <br> <tt>service stop</tt> - terminates the service, if it is running <br> <tt>service restart</tt> - Stops and then starts the service <br> <tt>service status</tt> - Indicates whether the service is currently running
|Manages a Windows system service that will automatically start enPortal when the server is started.  <br><br> <tt>service install</tt> - Creates a new service <br> <tt>service remove</tt> - Deletes the existing service
|<tt>See post_install step of installation documentation</tt>
|<tt>See post_install step of installation documentation</tt>
|<tt>service.bat install</tt>
|<tt>service.bat install</tt>
|-
|-
|}
|}


{{Tip|To check what version of Tomcat is being used by enPortal, use the command <tt>catalina.bat version</tt>}}
{{Tip|To check what version of Tomcat is being used by enPortal, use the command <tt>catalina.bat version</tt>}}


== Portal Commands ==
== Portal Commands ==
Line 77: Line 75:
|-
|-
|portal dbreset
|portal dbreset
|The dbreset command clears all configuration data from the system database, so that data can be re-loaded into the system.  The dbreset process includes multiple stages.  First, confirm the database deletion by entering the database admin password and entering "Yes" to confirm deletion.  Next, reset the load files by entering "y" to confirm.  Finally, once the database is cleared, select the appropriate option to re-load content into the database:<br><br>(B)ackup: Enter "B" to restore the system configuration by re-loading into the database the configuration files last saved by the XMLExport command in <tt>[Install_Home]/server/webapps/enportal/WEB-INF/xmlroot/server/content-backup/</tt>.<br>(S)tock: Enter "S" to restore the system configuration by re-loading into the database the stock content that would be loaded in a fresh installation of the product.  No custom configuration will be retained.<br>(N)one: Enter "N" to not load any content into the system.  This is not typically recommended, as the interface will generally not load without any base content.
|The dbreset command clears all configuration data from the system database, so that data can be re-loaded into the system.  The dbreset process includes multiple stages.  First, confirm the database deletion by entering the database admin password and entering "Yes" to confirm deletion.  Next, reset the load files by entering "y" to confirm.  Finally, once the database is cleared, select the appropriate option to re-load content into the database:<br><br>(B)ackup: Enter "B" to restore the system configuration by re-loading into the database the configuration files last saved by the XMLExport command in <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/content-backup/</tt>.<br>(S)tock: Enter "S" to restore the system configuration by re-loading into the database the stock content that would be loaded in a fresh installation of the product.  No custom configuration will be retained.<br>(N)one: Enter "N" to not load any content into the system.  This is not typically recommended, as the interface will generally not load without any base content.
|<tt>./portal.sh dbreset</tt>
|<tt>./portal.sh dbreset</tt>
|<tt>portal.bat dbreset</tt>
|<tt>portal.bat dbreset</tt>
Line 92: Line 90:
|-
|-
|portal keycreate
|portal keycreate
|enPortal integrates applications into a common interface. Most of these applications require a Username and Password for access. enPortal’s Single Sign-on feature saves these user credentials and automatically submits them to applications on behalf of the enPortal user. When these passwords are stored by enPortal, it is critical that they are securely encrypted so that they cannot be accessed by other parties.<br><br>The enPortal distribution includes a default encryption key that is used for securely storing authentication passwords in the database and XML files. You may choose to add a level of security to the system by creating a custom key for encrypting passwords.  The security of enPortal protects user credentials stored within the portal database. The user credentials are protected even if an attacker were to gain access to the database content (such as from a discarded backup) or an XML export of enPortal content. enPortal utilizes a one-way hashing algorithm for the storage of internal product passwords. External application passwords used for Single Sign-on are encrypted using strong encryption (specifically, the NIST sponsored AES algorithm). Creating a custom key will enhance security by creating a custom private key applicable to only that system.<br><br>If you create a custom encryption key, enPortal will create the file crypto.properties. This file does not exist in a fresh enPortal installation, and will not exist in any enPortal system that does not have a custom key. This file operates conceptually as a certificate that enPortal uses for encrypting passwords.  Once you create a custom key file, you must permanently retain the crypto.properties file for enPortal to be able to decrypt passwords. If you lose the crypto.properties file, all passwords will be lost.  The keycreate command is used to generate the custom crypto.properties file. You will generally only need to run this command once over the lifetime of the enPortal system. enPortal does not have to be running to execute the KeyCreate command.  After running the keycreate command, locate the new file:<br> <tt>[Install_Home]/server/webapps/enportal/WEB-INF/config/crypto.properties</tt><br> to confirm that the file was created successfully. If you are running a clustered enPortal system where multiple enPortal installations are sharing a single database, you must manually copy the crypto.properties and persist.properties files into the<br> <tt>[Install_Home]/server/webapps/enportal/WEB-INF/config/</tt><br> directory of each enPortal filesystem.
|enPortal is required to store certain passwords in a recoverable form for re-use. Refer to the [[enportal/5.5/admin/system_administration/security#Passwords_.26_Secrets|Product Security]] page for a complete list. These passwords are stored using AES encryption and the system default encryption key is 128-bits for compatibility reasons, although 192-bit and 256-bit keys are also supported. Please note that for key strengths over 128-bits either OpenJDK or the ''Unlimited Strength'' Java Cryptography Extension (JCE) is required.<br><br>When running this command you must first confirm to proceed, then prompted for the key length in bits. After running this command the <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/crypto.properties</tt> file will be created or updated. This file is automatically included in full archives. If running a clustered enPortal system, and depending on the deployment/update model, it may be necessary to copy this file to each server.<br><br>Although this command can be run with enPortal running, the enPortal process must be restarted for all stored keys to be re-encrypted using the new key.
|<tt>./portal.sh keycreate</tt>
|<tt>./portal.sh keycreate</tt>
|<tt>portal.bat keycreate</tt>
|<tt>portal.bat keycreate</tt>
|-
|-
|portal loadfilereset
|portal loadfilereset
|The loadfilereset command provides several options for loading content into the enPortal database.  This is the same command that is run by the dbreset command, except the dbreset command empties out the database before loading the content.  Note, it is generally recommended to use the dbreset command and the loadfilereset command should only be used in special cases.  The following options are available when running loadfilereset:<br><br>(B)ackup: Enter "B" to restore the system configuration by re-loading into the database the configuration files last saved by the XMLExport command in <tt>[Install_Home]/server/webapps/enportal/WEB-INF/xmlroot/server/content-backup/</tt>.<br>(S)tock: Enter "S" to restore the system configuration by re-loading into the database the stock content that would be loaded in a fresh installation of the product.  No custom configuration will be retained.<br>(N)one: Enter "N" to not load any content into the system.  This is not typically recommended, as the interface will generally not load without any base content.
|The loadfilereset command provides several options for loading content into the enPortal database.  This is the same command that is run by the dbreset command, except the dbreset command empties out the database before loading the content.  Note, it is generally recommended to use the dbreset command and the loadfilereset command should only be used in special cases.  The following options are available when running loadfilereset:<br><br>(B)ackup: Enter "B" to restore the system configuration by re-loading into the database the configuration files last saved by the XMLExport command in <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/content-backup/</tt>.<br>(S)tock: Enter "S" to restore the system configuration by re-loading into the database the stock content that would be loaded in a fresh installation of the product.  No custom configuration will be retained.<br>(N)one: Enter "N" to not load any content into the system.  This is not typically recommended, as the interface will generally not load without any base content.
|<tt>./portal.sh loadfilereset</tt>
|<tt>./portal.sh loadfilereset</tt>
|<tt>portal.bat loadfilereset</tt>
|<tt>portal.bat loadfilereset</tt>

Latest revision as of 11:34, 2 February 2015


There are certain activities that the enPortal administrator will complete through the use of command line utilities. This section details the available commands, including the purpose of each command and the options associated with that command.


How To Execute a Command Line Utility

Perform the following to execute the commands detailed on this page:

  1. Open a terminal or console
  2. Navigate to [Install_Home]/server/bin/
  3. Enter the command, followed by any necessary parameters


Tomcat Commands

enPortal runs as a standard Tomcat web application. This section details some of the Tomcat commands that are most commonly used by the enPortal administrator. For more detail on any commands in this section, the administrator should consult the applicable Tomcat documentation.


Command Description Unix Example Windows Example
startup Checks for valid enPortal license file and starts enPortal. If enPortal started successfully, the final message displayed in the console will be: "Server is started and ready for login. Listening on: [protocol], port: [port] (shutdown.port: [port])" ./startup.sh startup.bat
shutdown Terminates enPortal. ./shutdown.sh shutdown.bat
catalina Provides a number of additional Tomcat commands. For example, if startup is not working, the command catalina.bat run is an alternative startup command that will often give more feedback in the console as to the nature of the issue. ./catalina.sh run catalina.bat run
service Manages a Windows system service that will automatically start enPortal when the server is started.

service install - Creates a new service
service remove - Deletes the existing service 		See post_install step of installation documentation service.bat install
Template-tip.png
To check what version of Tomcat is being used by enPortal, use the command catalina.bat version

Portal Commands

This section details commands that can be used by the enPortal administrator to manage or configure the system.


Command Description Unix Example Windows Example
portal apply The restore process enables the enPortal administrator to restore previous data and configurations after installing a new version of enPortal. The two restore options are portal "restore" and portal "apply". The apply command skips over copying some of the config files from the archive JAR. It can be used, for example, when loading an archive on to a test server if you do not want the command to extract all of the system configuration settings and wipe out the local settings that are in place (for example, the license file). The list of files that is skipped by the apply command can be seen (and configured) in [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/export.properties under the section labeled "import.skip.apply". enPortal must be shut down before running this command. For more information on this command, see the Backup and Restore documentation. ./portal.sh apply –jar ../webapps/enportal/WEB-INF/archive/<name of backup jar file> portal.bat apply –jar ..\webapps\enportal\WEB-INF\archive\<name of backup jar file>
portal classexec The classexec command is only used in special cases. After writing a custom command, such as a utility to import data into enPortal from an external file, the command would be run using the classexec command. ./portal.sh classexec com.edgetech.sample.eportal.CreateAccounts -dmn System -uid

administrator -pwd mypwd -f ../accounts.txt

portal.bat classexec com.edgetech.sample.eportal.CreateAccounts -dmn System -uid

administrator -pwd mypwd -f ..\accounts.txt

portal cryptpw The cryptpw utility can be used to create encrypted passwords that can be used in place of plaintext passwords. The resulting password will be a randomized and encrypted password. The console will display the encrypted form of the password. ./portal.sh cryptpw myPassword portal.bat cryptpw myPassword
portal dbreset The dbreset command clears all configuration data from the system database, so that data can be re-loaded into the system. The dbreset process includes multiple stages. First, confirm the database deletion by entering the database admin password and entering "Yes" to confirm deletion. Next, reset the load files by entering "y" to confirm. Finally, once the database is cleared, select the appropriate option to re-load content into the database:

(B)ackup: Enter "B" to restore the system configuration by re-loading into the database the configuration files last saved by the XMLExport command in [INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/content-backup/.
(S)tock: Enter "S" to restore the system configuration by re-loading into the database the stock content that would be loaded in a fresh installation of the product. No custom configuration will be retained.
(N)one: Enter "N" to not load any content into the system. This is not typically recommended, as the interface will generally not load without any base content. 		./portal.sh dbreset portal.bat dbreset
portal dbsetup The dbsetup command launches a graphical database configuration utility. By default, enPortal uses an embedded H2 database for storing basic system configuration such as users or channel definitions. However, some customers choose to use an alternate database such as Oracle or SQL Server. The dbsetup utility assists with configuring this alternate database connection, and provides a test button to verify whether enPortal can successfully connect to the database. Once the test is successful, start enPortal normally and it will be using the alternate database. An alternative to using this command is to directly modify the file: [Install_Home]/server/webapps/enportal/WEB-INF/config/persist.properties ./portal.sh dbsetup portal.bat dbsetup
portal filesimport The filesimport command loads a set of files from a JAR archive into the enPortal filesystem. This is a legacy command that should only be used in special cases, as its functionality has been replaced by the apply and restore commands which load files and XML into the system for a full restore. ./portal.sh filesImport -jar fileBundle.jar portal.bat filesImport -jar fileBundle.jar
portal keycreate enPortal is required to store certain passwords in a recoverable form for re-use. Refer to the Product Security page for a complete list. These passwords are stored using AES encryption and the system default encryption key is 128-bits for compatibility reasons, although 192-bit and 256-bit keys are also supported. Please note that for key strengths over 128-bits either OpenJDK or the Unlimited Strength Java Cryptography Extension (JCE) is required.

When running this command you must first confirm to proceed, then prompted for the key length in bits. After running this command the [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/crypto.properties file will be created or updated. This file is automatically included in full archives. If running a clustered enPortal system, and depending on the deployment/update model, it may be necessary to copy this file to each server.

Although this command can be run with enPortal running, the enPortal process must be restarted for all stored keys to be re-encrypted using the new key. 		./portal.sh keycreate portal.bat keycreate
portal loadfilereset The loadfilereset command provides several options for loading content into the enPortal database. This is the same command that is run by the dbreset command, except the dbreset command empties out the database before loading the content. Note, it is generally recommended to use the dbreset command and the loadfilereset command should only be used in special cases. The following options are available when running loadfilereset:

(B)ackup: Enter "B" to restore the system configuration by re-loading into the database the configuration files last saved by the XMLExport command in [INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/content-backup/.
(S)tock: Enter "S" to restore the system configuration by re-loading into the database the stock content that would be loaded in a fresh installation of the product. No custom configuration will be retained.
(N)one: Enter "N" to not load any content into the system. This is not typically recommended, as the interface will generally not load without any base content. 		./portal.sh loadfilereset portal.bat loadfilereset
portal restore The restore process enables the enPortal administrator to restore previous data and configurations after installing a new version of enPortal. The two restore options are portal "restore" and portal "apply". The "restore" command is intended for doing a complete rebuild of AppBoard, such as when you are migrating AppBoard to a new server or upgrading to a new AppBoard version. It will copy all of the files from the archive JAR on to the destination server where you are running the command. enPortal must be shut down before running this command. For more information on this command, see the Backup and Restore documentation. ./portal.sh restore –jar ../webapps/enportal/WEB-INF/archive/<name of backup jar file> portal.bat restore –jar ..\webapps\enportal\WEB-INF\archive\<name of backup jar file>
portal transform The transform command is used as a verification utility when working with XSLT data transforms in AppBoard. The utility has many options, which can be seen by running the portal transform command without any arguments. The command can be used to verify that a transform is working before implementing it in the system. ./portal.sh transform -IN <XML URL> -XSL <Transformation URL> -OUT output.txt portal.bat transform -IN <XML URL> -XSL <Transformation URL> -OUT output.txt
portal version The version command will note in the console information about the enPortal system. Information returned in the console will include the product version number, build date/time, and version of Java being used. ./portal.sh version portal.bat version
portal xmlvalidate The xmlvalidate command is a legacy option that not commonly used. It can be used to analyze an XML file and verify that the file is formatted correctly for loading into enPortal. An XML file should be validated against its DTD file so that discrepancies are determined before the file is loaded into the enPortal system. The command takes the URI of the XML file passed in as an argument and validates it based on the named DTD, or a DTD file referenced in the XML file. ./portal.sh xmlvalidate ../webapps/enportal/WEB-INF/xmlroot/server/sample/msp/roles.xml portal.bat xmlvalidate ..\webapps\enportal\WEB-INF\xmlroot\server\sample\msp\roles.xml

Unix Commands

This section details commands that would be of use to an administrator managing enPortal on a Unix file system.


Perform the following to execute the commands detailed in this section:

  1. Open a terminal or console
  2. Navigate to [Install_Home]/server/bin/helpers/
  3. Enter the command, followed by any necessary parameters


Command Description Example
fix_permissions When new files are added into the enPortal file system, it is possible that there could be issues with the permissions on those files. Files are sometimes added, for example, when restoring archives or migrating content from one server to another. The fix_permissions script will ensure that all of the files in the file system have the proper permissions to work in enPortal. Note, this command does not need to be run after running post_install, because it is included as part of the post_install script. ./fix_permissions.sh
post_install On Linux and UNIX systems, as part of the initial installation it is necessary to run this script to update file ownership and permissions, and set some initial configuration parameters. For more information on this command as part of the product installation, see Installation. ./post_install.sh
unix_service The post_install process (see Installation) handles the creation of a Unix service. However, in some cases you will need to manually remove the Unix service, such as when the enPortal installation directory has to be moved, or enPortal is to be removed from the server. In such cases, this can be done using the unix_services utility as root. ./unix_service.sh remove
Retrieved from "http://ab.edge-technologies.com/docs/index.php?title=Enportal/5.5/admin/system_administration/CLI_utilities&oldid=7156"