TRAFFIC_LAYOUT(1)

NAME
traffic_layout - Traffic Server sandbox management tool

SYNOPSIS

traffic_layout SUBCOMMAND [OPTIONS]

ENVIRONMENT

    TS_RUNROOT
        The path to the run root file. It has the same effect as the command line option --run-root.

DESCRIPTION

Document for the traffic_layout about the runroot. This feature is for the setup of Traffic Server runroot. It will create a runtime sandbox for any program of Traffic Server to run under. For details about runroot for programs, please refer to developer-guide/layout/runroot.en.

USAGE

First we need to create a runroot. It can be created simply by calling command init.

            traffic_layout init --path /path/to/runroot

A runroot will be created in /path/to/runroot, available for other programs to use. If the path is not specified, the current working directory will be used.

    For example, to run traffic_manager, using the runroot, there are several ways:

        1.  /path/to/runroot/bin/traffic_manager

        2.  traffic_manager --run-root=/path/to/runroot

        3.  traffic_manager --run-root=/path/to/runroot/runroot.yaml

        4.  Set TS_RUNROOT to /path/to/runroot and run traffic_manager

        5.  Run traffic_manager with /path/to/runroot as current working directory

NOTE:
        if none of the above is found as runroot, runroot will not be used and the program will fall back to the default.

SUBCOMMANDS

  init

Use the current working directory or the specific path to create runroot. The path can be absolute or relative.

    workflow:

        1.  Create a sandbox directory for programs to run under.

        2.  Copy and symlink build time directories and files to the sandbox, allowing users to modify freely.

        3.  Emit a YAML file that defines layout structure for other programs to use (relative path).

Example:

            traffic_layout init (--path /path/to/sandbox/) (--force) (--absolute) (--copy-style=[HARD/SOFT/FULL]) (--layout=special_layout.yml)

For the --layout=[<YAML file>] option, a custom layout can be used to construct a runroot. Below is an example of customized yaml file (custom.yml) to construct.

            prefix: ./runroot
            exec_prefix: ./runroot
            bindir: ./runroot/custom_bin
            sbindir: ./runroot/custom_sbin
            sysconfdir: ./runroot/custom_sysconf
            datadir: ./runroot/custom_data
            includedir: ./runroot/custom_include
            libdir: ./runroot/custom_lib
            libexecdir: ./runroot/custom_libexec
            localstatedir: ./runroot/custom_localstate
            runtimedir: ./runroot/custom_runtime
            logdir: ./runroot/custom_log
            cachedir: ./runroot/custom_cache

If traffic_layout init --layout="custom.yml" is executed, a runroot following the format above will be created.

NOTE:
        storage.config does not use the cachedir value, but makes its relatives paths relative to the base prefix. So please update the directory for cache in storage.config according to the customized runroot.

  remove

    Find the sandbox to remove in following order:

        1.  specified in --path as absolute or relative.

        2.  current working directory.

        3.  installed directory.

Example:

            traffic_layout remove (--path /path/to/sandbox/) (--force)

  verify

Verify the permission of the sandbox. The permission issues can be fixed with --fix option. --with-user option can be used to verify the permission of the runroot for specific user.

Example:

            traffic_layout verify (--path /path/to/sandbox/) (--fix) (--with-user root)

WARNING:
        If a custom layout is used and system files are included in some directories, --fix option might potentially have unexpected behaviors. For example, if sysconfdir is defined as /etc instead of /etc/trafficserver in runroot.yaml, --fix may perform permission changes on the system configuration files. With normally created runroot with default layout, there is no such issue since Traffic Server related files are filtered.

OPTIONS

    --run-root=[<path>]
        Use the run root file at path.

    -V, --version
        Print version information and exit.

    -h, --help
        Print usage information and exit.

    -p, --path
        Specify the path of runroot for commands (init, remove, verify).

  init

    -f, --force
        Force init will create sandbox even if the directory is not empty.

    -a, --absolute
        Put directories in the YAML file in the form of absolute paths when creating.

    -c, --copy-style [HARD/SOFT/FULL]
        Specify the way of copying executables when creating runroot. HARD means hard link. SOFT means symlink. FULL means full copy.

    -l, --layout [<YAML file>]
        Use specific layout (providing YAML file) to create runroot.

  remove

    `-f`, `--force`
        Force remove will remove the directory even if it has no YAML file.

  verify

    -x, --fix
        Fix the permission issues verify found. --fix requires root privilege (sudo).

    -w, --with-user
        Verify runroot with certain user. The value can be passed in as the username or # followed by uid.

COPYRIGHT
2024, dev@trafficserver.apache.org