4. The dm Shell

The dm Shell is a command line utility that allows you to examine artifacts currently installed to a particular dm Server instance, manage the lifecycle of the installed artifacts, install new artifacts, and shutdown the server. You can install, examine, and manage the lifecycle of the following artifacts:

You can run the dm Shell locally or remotely by using ssh. The dm Shell is similar to the Equinox shell, but with added features such as tab completion and command history. Tab completion allows you to enter a partial command, and then press the Tab key and let the dm Shell show you a list of possible commands. To get a command history, simply use the up and down arrows.

4.1 Using the dm Shell

You invoke the dm Shell locally by passing the -shell flag to the startup.sh (Unix) or startup.bat (Windows) command that starts up dm Server. For example, on Unix:

prompt$ SERVER_HOME/bin/startup.sh -shell

You will see status messages for the dm Kernel starting, and then the dm Shell commmand line utility takes over. You can still view the console log messages by looking at the $SERVER_HOME/serviceability/eventlogs/event.log file. After you get the dm Shell splash screen, you can enter commands at the :> prompt. Enter help for a list of all available commands. For example:

prompt$ cd $SERVER_HOME/bin
prompt$ ./startup.sh -shell

[2009-11-06 14:27:26.620] startup-tracker              <KE0001I> Kernel starting.
[2009-11-06 14:27:31.873] startup-tracker              <KE0002I> Kernel started.
[2009-11-06 14:27:32.155] system-artifacts             <DE0056I> Installing plan 'com.springsource.server.web' version '2.0.0'.
[2009-11-06 14:27:32.659] Thread-2                     <SH0001I> dm Kernel ssh shell available on port 2401.

    @@@ ***                                                              
   @@@ *****           .__.                  .__.            .__.  .__.  
  @@@@ ******        __|  |  _____     _____.|  |__    ____  |  |  |  |  
  @@@@@@ ****       / __  | /     \   /  ___/|  |  \ ./ __ \ |  |  |  |  
   @@@@@ ***       / /_/  ||  Y Y  \  \___ \ |   Y  \\  ___/ |  |__|  |__
    @@@ ***        \______||__|_|__/ /_____/ |___|__/ \____/ |____/|____/

Type 'help' to see the available commands.
:> help


    bundle - Management and examination of bundle artifacts
    config - Management and examination of configuration artifacts
    help
    install - Install (deploy) an artifact to the server
    package - Management and examination of exported packages
    par - Management and examination of PAR artifacts
    plan - Management and examination of plan artifacts
    service - Examination of services
    shutdown
:> 

To invoke dm Shell remotely, use the ssh command with the following parameters:

  • Use the -p shell.port option to pass the port number where the dm Shell listens; the default value is 2401. You can change this port by editing the value of the shell.port property in the $SERVER_HOME/conf/com.springsource.kernel.properties configuration file.
  • Use the user@host parameter to specify the administration user; you will be prompted for a password. The default administration user/password is admin/springsource. You can change the administration user by updating the role.admin value in the $SERVER_HOME/conf/com.springsource.kernel.users.properties file. Use the user.admin to change the administration user's password.

The following example shows how to invoke the dm Shell using ssh on the local computer using the default port, user, and password:

prompt$ ssh -p 2401 [email protected]
[email protected]'s password:

    @@@ ***                                                              
   @@@ *****           .__.                  .__.            .__.  .__.  
  @@@@ ******        __|  |  _____     _____.|  |__    ____  |  |  |  |  
  @@@@@@ ****       / __  | /     \   /  ___/|  |  \ ./ __ \ |  |  |  |  
   @@@@@ ***       / /_/  ||  Y Y  \  \___ \ |   Y  \\  ___/ |  |__|  |__
    @@@ ***        \______||__|_|__/ /_____/ |___|__/ \____/ |____/|____/

Type 'help' to see the available commands.
:> 

Available dm Shell Commands

The following table lists the dm Shell commands; each command in turn has a variety of options that you can specify, depending on what you want to do, such as start a bundle or refresh a plan. The reference documentation about each command provides the full list of available options.

Table 4.1. dm Shell Commands

Command Description
exitExit from the dm Shell session.
bundleUsed to manage and display information about bundle artifacts.
configUsed to manage and display information about configuration artifacts.
packageUsed to manage and display information about exported packages.
parUsed to manage and display information about PAR artifacts.
planUsed to manage and display information about plan artifacts.
serviceDisplays information about services in the OSGi registry.
installUsed to install an artifact to dm Server.
shutdownShuts down the dm Server instance to which the dm Shell is connected.
helpDisplay help about the list of available commands, as well as more detailed help about individual commands.