TRAFFIC_LAYOUT(1)

💖 TRAFFIC_LAYOUT 💖

okay bestie, so this is traffic_layout, the Traffic Server sandbox management tool, and it's from the Apache Traffic Server manual (section 1, the user commands, you know the vibe) 💅

---

✨ SYNOPSIS ✨

traffic_layout SUBCOMMAND [OPTIONS]

that's it. that's the whole shape of it. subcommand first, options after. slay 🎀

---

🌸 ENVIRONMENT 🌸

• TS_RUNROOT — the path to the run root file. it does literally the exact same thing as the command line option --run-root. same energy, different door 🚪✨

---

🦋 DESCRIPTION 🦋

so this page is all about the runroot. this feature exists so you can set up a Traffic Server runroot — it makes a runtime sandbox that any program of Traffic Server can run inside of 🏠✨

and if you want the full deep dive on runroot for programs, the original points you at developer-guide/layout/runroot.en. go read it, it's giving documentation 💜

---

🌈 USAGE 🌈

first things first, we need to create a runroot. easiest way is just calling the init command, no cap:

traffic_layout init --path /path/to/runroot

boom 💥 a runroot gets created at /path/to/runroot and now it's available for other programs to use. and if you don't specify a path? it just uses the current working directory. flexible, we love her 🫶

for example, say you wanna run traffic_manager using the runroot. there are several ways, pick your fighter:

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. so like, if you skip all five, don't come crying to me 😭 it just goes back to default behavior.

---

👑 SUBCOMMANDS 👑

🎀 init 🎀

use the current working directory, or a specific path, to create a runroot. the path can be absolute or relative — she's not picky 💅

the workflow, step by step:

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)

now, about the --layout=[<YAML file>] option — you can use a custom layout to construct a runroot. below is an example of a 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

so if you run traffic_layout init --layout="custom.yml", a runroot following that exact format above gets created. iconic 🎀

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. this one matters, don't skip it 🫠

🧚 remove 🧚

it finds the sandbox to remove in this 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 🍓

this one verifies the permission of the sandbox. and if it finds permission issues, you can fix them with the --fix option ✨ the --with-user option can be used to verify the permission of the runroot for a 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, the --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 a normally created runroot with the default layout, there is no such issue since Traffic Server related files are filtered. so like… be careful, bestie, that's a whole system config situation 💀

---

💅 OPTIONS 💅

• --run-root=[<path>] — use the run root file at path.
• -V, --version — print version information and exit. bye 👋
• -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 the sandbox even if the directory is not empty. bold. love that for her 🔥
• -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. choose your destiny ✨
• -l, --layout [<YAML file>] — use a 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). so yeah, you're gonna need the power 👑
• -w, --with-user — verify runroot with a certain user. the value can be passed in as the username, or # followed by uid.

---

💜 COPYRIGHT 💜

2026, dev@trafficserver.apache.org

---

and that's the whole page, bestie 🫶 shoutout to the Apache Traffic Server girlies for writing it, version 9.2, dated Feb 12, 2026 — go forth and sandbox responsibly 💖✨🎀