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

       2023, dev@trafficserver.apache.org