Command-line Arguments

Canton supports a variety of command line arguments. Please run bin/canton –help to see all of them. Here, we explain the most relevant ones.

Selecting a Configuration

Canton requires a configuration file to run. There is no default topology configuration built in and therefore, the user needs to at least define what kind of node (domain or participant) and how many he wants to run in the given process. Sample configuration files can be found in our release package, under the examples directory.

When starting Canton, configuration files can be provided using

bin/canton --config conf_filename -c conf_filename2

which will start Canton by merging the content of conf_filename2 into conf_filename. Both options -c and –config are equivalent. If several configuration files assign values to the same key, the first value is taken. The section on static configuration explains how to write a configuration file.

Run Modes

Canton can run in three different modes, depending on the desired environment and task.

Interactive Console

The default and recommended method to run Canton is in the interactive mode. This is the mode Canton will start in by default. The process will start a command line interface (REPL) which allows to conveniently operate, modify and inspect the Canton application.

In this mode, all errors will be reported as CommandExcecutionException to the console, but Canton will remain running.

The interactive console can be started together with a script, using the –boostrap-script=… option. The script uses the same syntax as the console.

This is the recommended way to run Canton (for now).

For server use on Linux / OSX, we recommend to run the application using the screen command:

screen -S canton -d -m ./bin/canton -c ...

will start the Canton process in a screen session named canton which does not terminate on user-logout and therefore allows to inspect the Canton process whenever necessary.

A previously started process can be joined using

screen -r canton

and an active screen session can be detached using CTRL-A + D (in sequence). Be careful and avoid typing CTRL-D, as it will terminate the session. The screen session will continue to run even if you log out of the machine.

Remote Console Mode

You can also run the console process separate from the participant or domain nodes. Some advanced console commands (e.g. for testing) that require in-process access to the node will not be available, but all commands that run over the administrative GRPC APIs will work.

Running the console on the remote node requires a separate, albeit limited configuration with the information on how to connect to the admin and ledger-api.

For a participant, you need something like

canton {
  remote-participants {
    remoteParticipant1 {
      admin-api {
        port = 10012
        address = 127.0.0.1 // is the default value if omitted
      }
      ledger-api {
        port = 10011
        address = 127.0.0.1 // is the default value if omitted
      }
    }
  }
}

whereas for a domain, a configuration would look like

canton {
  remote-domains {
    remoteDomain {
      admin-api {
        port = 10019
        address = 127.0.0.1 // is the default value if omitted
      }
    }
  }
}

Headless Script Mode

For testing and scripting purposes, Canton can also start in headless script mode:

bin/canton run <script-path> --config ...

In this case, commands are specified in a script rather than executed interactively. Any errors with the script or during command execution should cause the Canton process to exit with a non-zero exit code.

This mode is sometimes useful for testing, but we are not convinced yet that we’ll keep it in a stable version.

Daemon

If the console is undesired, Canton can be started in daemon mode

bin/canton daemon --config ...

All configured entities will be automatically started and will resume operation. Any failures encountered during start up will immediately shutdown the Canton process with a non-zero exit code. This mode is interesting if a third party administration tool is used with Canton.

Java Virtual Machine Arguments

The bin/canton application is a convenient wrapper to start a Java virtual machine running the Canton process. The wrapper supports providing additional JVM options using the JAVA_OPTS environment variable:

JAVA_OPTS=" -Xmx2G" ./bin/canton --config ...

Logging

Canton uses Logback as the logging library. All Canton logs will derive from the root logger com.digitalasset.canton. By default, Canton will write a log to the file log/canton.log using the INFO log-level.

Using the flag -v (or --verbose) will increase the log-level of canton classes. Using -d (or --debug) will increase logging even further. Using -f (or --debug-full) will increase logging for the root logger instead of just for canton classes.

The log-file can be truncated on startup using --truncate-log.

A custom logback configuration can be provided using JAVA_OPTS.

JAVA_OPTS="-Dlogback.configurationFile=./path-to-file.xml" ./bin/canton --config ...

A starting point for a custom logback.xml file would be

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" debug="false">

    <!-- propagate logback changes to jul handlers -->
    <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator">
        <resetJUL>true</resetJUL>
    </contextListener>

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%highlight([%level] %logger{10} %replace(cid:%mdc{correlation-id} ){'cid: ', ''}: %msg) %n
            </pattern>
        </encoder>
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>${STDOUT_LOG_LEVEL:-WARN}</level>
        </filter>
    </appender>
    <!-- using rolling file appender to keep log files small and delete old logs -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>log/canton.log</file>
        <append>true</append>
        <!-- don't force a flush on each log-line (faster, but may miss logs when crashing) -->
        <immediateFlush>false</immediateFlush>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- hourly rollover and compress (gz), change pattern if you want different roll-overs -->
            <fileNamePattern>log/canton.%d{yyyy-MM-dd-HH}.log.gz</fileNamePattern>
            <!-- keep max 12 archived log files -->
            <maxHistory>12</maxHistory>
        </rollingPolicy>
        <encoder>
            <!-- include correlation-id in log-line -->
            <pattern>%date [%thread] %-5level %logger{35} %replace(cid:%mdc{correlation-id} ){'cid: ', ''}- %msg%n
            </pattern>
        </encoder>
    </appender>

    <!--
        Include the Canton rewrite appender to rewrite certain log levels of certain messages

        The Canton rewrite appender expects two appender-ref: FILE and STDOUT and will create
        a new appender named REWRITE_LOG_LEVEL.
        This appender allows us to change the log-level of some log messages created by certain
        libraries such that we don't get messy and unnecessary warnings or errors.
    -->
    <include resource="rewrite-appender.xml"/>

    <root level="INFO">
        <appender-ref ref="REWRITE_LOG_LEVEL"/>
    </root>

</configuration>

For further debuggability, Canton provides a correlation-id which allows to trace the processing of requests through the system. The correlation-id is exposed to logback through the mapping diagnostic context and can be included in the logback output pattern using %mdc{correlation-id}.

The correlation-id needs to be enabled by setting the canton.parameters.trace-context-propagation = enabled configuration option.