49. Monitoring and management using a remote shell
Prev Part V. Spring Boot Actuator: Production-ready features Next

49. Monitoring and management using a remote shell

Spring Boot supports an integrated Java shell called ‘CRaSH’. You can use CRaSH to ssh or telnet into your running application. To enable remote shell support, add the following dependency to your project:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-remote-shell</artifactId>
 </dependency>
[Tip]Tip

If you want to also enable telnet access you will additionally need a dependency on org.crsh:crsh.shell.telnet.

[Note]Note

CRaSH requires to run with a JDK as it compiles commands on the fly. If a basic help command fails, you are probably running with a JRE.

49.1 Connecting to the remote shell

By default the remote shell will listen for connections on port 2000. The default user is user and the default password will be randomly generated and displayed in the log output. If your application is using Spring Security, the shell will use the same configuration by default. If not, a simple authentication will be applied and you should see a message like this:

Using default password for shell access: ec03e16c-4cf4-49ee-b745-7c8255c1dd7e

Linux and OSX users can use ssh to connect to the remote shell, Windows users can download and install PuTTY.

$ ssh -p 2000 user@localhost

user@localhost's password:
  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v1.4.3.RELEASE) on myhost

Type help for a list of commands. Spring Boot provides metrics, beans, autoconfig and endpoint commands.

49.1.1 Remote shell credentials

You can use the management.shell.auth.simple.user.name and management.shell.auth.simple.user.password properties to configure custom connection credentials. It is also possible to use a ‘Spring Security’ AuthenticationManager to handle login duties. See the CrshAutoConfiguration and ShellProperties Javadoc for full details.

49.2 Extending the remote shell

The remote shell can be extended in a number of interesting ways.

49.2.1 Remote shell commands

You can write additional shell commands using Groovy (see the CRaSH documentation for details). Due to limitations in CRaSH’s Java compiler, commands written in Java are not supported. By default Spring Boot will search for commands in the following locations:

  • classpath*:/commands/**
  • classpath*:/crash/commands/**
[Tip]Tip

You can change the search path by settings a shell.command-path-patterns property.

[Note]Note

If you are using an executable archive, any classes that a shell command depends upon must be packaged in a nested jar rather than directly in the executable jar or war.

Here is a simple ‘hello’ command that could be loaded from src/main/resources/commands/hello.groovy

package commands

import org.crsh.cli.Command
import org.crsh.cli.Usage
import org.crsh.command.InvocationContext

class hello {

    @Usage("Say Hello")
    @Command
    def main(InvocationContext context) {
        return "Hello"
    }

}

Spring Boot adds some additional attributes to InvocationContext that you can access from your command:

Attribute NameDescription

spring.boot.version

The version of Spring Boot

spring.version

The version of the core Spring Framework

spring.beanfactory

Access to the Spring BeanFactory

spring.environment

Access to the Spring Environment

49.2.2 Remote shell plugins

In addition to new commands, it is also possible to extend other CRaSH shell features. All Spring Beans that extend org.crsh.plugin.CRaSHPlugin will be automatically registered with the shell.

For more information please refer to the CRaSH reference documentation.

Prev Up Next
48. Monitoring and management over JMX Home 50. Metrics