.\" SPDX-License-Identifier: GPL-2.0-only
.TH TUNA "8" "July 2026" "tuna" "System Administration Utilities"
.SH NAME
tuna \- program for tuning running processes
.SH SYNOPSIS
.B tuna
[\fIOPTIONS\fR]
.SH DESCRIPTION
This manual page explains the \fBtuna\fR program. The program can be used to change the attributes of application and kernel threads. \fBtuna\fR can operate on IRQs by name or number, and tasks or threads by process ID or command-line. CPUs and sets of CPUs can be specified by CPU or socket number. IRQ names and process command-lines can include wildcards.
.PP
\fBtuna\fP can change scheduling policy, scheduler priority and processor affinity for processes and process threads. \fBtuna\fR can also change the processor affinity for interrupts. \fBtuna\fR supports cgroup v2 cpusets for CPU and memory node isolation, providing fine-grained control over which processes can run on which CPUs.
When \fBtuna\fR is invoked without any options it starts up in its graphical interface mode. This manual page explains only the command\-line options for \fBtuna\fR
.SH "GLOBAL OPTIONS"
.TP
\fB\-h\fR, \fB\-\-help\fR
Print a list of options. \fBtuna\fR will exit after this action, ignoring the remainder of the command-line.
.TP
\fB\-v\fR, \fB\-\-version\fR
Show version
.TP
\fB\-L\fR, \fB\-\-logging\fR=\fILOG-LEVEL\fR
Log application details to file for given LOG-LEVEL
.TP
\fB\-D\fR, \fB\-\-debug\fR
Print DEBUG level logging details to console
.TP
\fB\-w\fR, \fB\-\-warn\fR
Warn when thread/IRQ patterns match nothing
.SH "COMMANDS"
.TP
\fBtuna cpu_power\fR
usage: tuna-cmd.py cpu_power [-h] (-c CPU-LIST)

Set or query the idle (power) states of all or a selection of cpus in the CPU-LIST. Modifiers \fB\-c\fR may be used to pass the CPU-LIST of cpus to perform the command on.

optional arguments:
  -h, --help            show this help message and exit
  -i, --idle-info       Print general idle information for the selected CPUs, including
                        index values for IDLE-STATE.
  -s, --status IDLE-STATE
                        Print whether IDLE-STATE is enabled on the selected CPUs.
  -d, --disable IDLE-STATE
                        Disable IDLE-STATE on the selected CPUs.
  -e, --enable IDLE-STATE
                        Enable IDLE-STATE on the selected CPUs.
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
.TP
\fBtuna isolate\fR
usage: tuna-cmd.py isolate [-h] (-c CPU-LIST | -S CPU-SOCKET-LIST | -N)
                           [--cpuset [NAME]] [--cpuset-housekeeping ...]

Move all allowed threads and IRQs away from CPU\-LIST. Requires \fB\-c\fR, \fB-S\fR, or \fB-N\fR.

optional arguments:
  -h, --help            show this help message and exit
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
  --cpuset [NAME]       Use cpusets for isolation with optional name (default: tuna_isolated,
                        partition=isolated)
  --cpuset-housekeeping [NAME] CPU-LIST
                        Create housekeeping cpuset: [NAME] CPU-LIST (default name:
                        tuna_housekeeping, partition=member)
.TP
\fBtuna include\fR
usage: tuna-cmd.py include [-h] (-c CPU-LIST | -S CPU-SOCKET-LIST | -N)

Allow all allowed threads and IRQs to run on CPU\-LIST. Requires \fB\-c\fR, \fB-S\fR, or \fB-N\fR.

optional arguments:
  -h, --help            show this help message and exit
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
.TP
\fBtuna move\fR
usage: tuna-cmd.py move [-h] (-c CPU-LIST | -S CPU-SOCKET-LIST | -N | --cpuset CPUSET-NAME)
                        [-t THREAD-LIST] [-q IRQ-LIST] [-U] [-K]

Move selected entities to CPU\-LIST or cpuset. Requires \fB\-c\fR, \fB-S\fR, \fB-N\fR, or \fB--cpuset\fR and \fB-t\fR or \fB-q\fR.

optional arguments:
  -h, --help            show this help message and exit
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
  --cpuset CPUSET-NAME  Move threads/IRQs into cpuset (cgroup v2) instead of
                        setting CPU affinity
  -t THREAD-LIST, --threads THREAD-LIST
                        THREAD-LIST affected by commands
  -q IRQ-LIST, --irqs IRQ-LIST
                        IRQ-LIST affect by commands
  -U, --no_uthreads     Operations will not affect user threads
  -K, --no_kthreads     Operations will not affect kernel threads
.TP
\fBtuna spread\fR
usage: tuna-cmd.py spread [-h] (-c CPU-LIST | -S CPU-SOCKET-LIST | -N)
                          [-t THREAD-LIST] [-q IRQ-LIST] [-U] [-K]

Spread selected entities over CPU-LIST. The specified threads and IRQs are each assigned to one cpu in CPU-LIST. Requires \fB\-c\fR, \fB-S\fR, or \fB-N\fR and \fB-t\fR or \fB-q\fR.

optional arguments:
  -h, --help            show this help message and exit
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
  -t THREAD-LIST, --threads THREAD-LIST
                        THREAD-LIST affected by commands
  -q IRQ-LIST, --irqs IRQ-LIST
                        IRQ-LIST affect by commands
  -U, --no_uthreads     Operations will not affect user threads
  -K, --no_kthreads     Operations will not affect kernel threads
.TP

\fBtuna priority\fR
usage: tuna-cmd.py priority [-h] -t THREAD-LIST [-C] POLICY:RTPRIO

Set thread scheduler tunables: POLICY and RTPRIO. POLICY is one of OTHER, FIFO, RR, or BATCH. Provide POLICY, RTPRIO, or POLICY:RTPRIO separated by ":". If only POLICY is set, the RT priority will default to 1 if the policy is RT, and 0 otherwise. If only RTPRIO is specified, policy will not be changed.

positional arguments:
  POLICY:RTPRIO         Set thread scheduler tunables: POLICY and RTPRIO

optional arguments:
  -h, --help            show this help message and exit
  -t THREAD-LIST, --threads THREAD-LIST
                        THREAD-LIST affected by commands
  -C, --affect_children
                        Operation will affect children threads
.TP
\fBtuna run\fR
usage: tuna-cmd.py run [-h] [-c CPU-LIST | -S CPU-SOCKET-LIST | -N | --cpuset CPUSET-NAME]
                       [-p PRIORITY] [-b]
                       COMMAND

Run the COMMAND. The entire command line must be provided inside "quotes". Modifiers \fB-c\fR, \fB-S\fR, \fB--cpuset\fR and \fB-p\fR can be used to set the affinity and scheduler tunables of the given COMMAND.

positional arguments:
  COMMAND               fork a new process and run the "COMMAND"

optional arguments:
  -h, --help            show this help message and exit
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
  --cpuset CPUSET-NAME  Run process in specified cpuset (cgroup v2) instead of
                        setting CPU affinity
  -p PRIORITY, --priority PRIORITY
                        Set thread scheduler tunables: POLICY and RTPRIO
  -b, --background      Run command as background task

.TP
\fBtuna save\fR
usage: tuna-cmd.py save [-h] [-c CPU-LIST | -S CPU-SOCKET-LIST | -N]
                        [-t THREAD-LIST]
                        FILENAME

Save kthreads sched tunables to FILENAME

positional arguments:
  FILENAME              Save kthreads sched tunables to this file

optional arguments:
  -h, --help            show this help message and exit
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
  -t THREAD-LIST, --threads THREAD-LIST
                        THREAD-LIST affected by commands
.TP
.\"\fBtuna apply\fR
.\"usage: tuna-cmd.py apply [-h] profilename
.\"
.\"Apply changes described in profile
.\"
.\"positional arguments:
.\"  profilename  Apply changes described in this file
.\"
.\"optional arguments:
.\"  -h, --help   show this help message and exit
.\"
.TP
\fBtuna show_threads\fR
usage: tuna-cmd.py show_threads [-h] [-c CPU-LIST | -N | -S CPU-SOCKET-LIST]
                                [-t THREAD-LIST | -q IRQ-LIST] [-U] [-K] [-C]
                                [-n] [-G] [--cpuset CPUSET-NAME] [-z]

Show thread list

optional arguments:
  -h, --help            show this help message and exit
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -t THREAD-LIST, --threads THREAD-LIST
                        THREAD-LIST affected by commands
  -q IRQ-LIST, --irqs IRQ-LIST
                        IRQ-LIST affect by commands
  -U, --no_uthreads     Operations will not affect user threads
  -K, --no_kthreads     Operations will not affect kernel threads
  -C, --affect_children
                        Operation will affect children threads
  -n, --show_sockets    Show network sockets in use by threads (requires inet_diag module)
  -G, --cgroups         Display the processes with the type of cgroups they
                        are in
  --cpuset CPUSET-NAME  Show only threads in the specified cpuset
  -z, --spaced          Display spaced view for cgroups

.TP
\fBtuna show_irqs\fR
usage: tuna-cmd.py show_irqs [-h] [-c CPU-LIST | -N | -S CPU-SOCKET-LIST]
                             [-q IRQ-LIST]

Show IRQ list

optional arguments:
  -h, --help            show this help message and exit
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -q IRQ-LIST, --irqs IRQ-LIST
                        IRQ-LIST affect by commands

.TP
\fBtuna show_configs\fR
usage: tuna-cmd.py show_configs [-h]

List preloaded profiles

optional arguments:
  -h, --help  show this help message and exit

.TP
\fB tuna what_is\fR
usage: tuna-cmd.py what_is [-h] THREAD-LIST

Provides help about selected entities

positional arguments:
  THREAD-LIST  THREAD-LIST affected by commands

optional arguments:
  -h, --help   show this help message and exit
.TP
\fB tuna gui\fR
usage: tuna-cmd.py gui [-h] [-d] [-R MSEC]
                       [-c CPU-LIST | -N | -S CPU-SOCKET-LIST] [-U] [-K]

Start the GUI

optional arguments:
  -h, --help            show this help message and exit
  -d, --disable_perf    Explicitly disable usage of perf in GUI for process
                        view
  -R MSEC, --refresh MSEC
                        Refresh the GUI every MSEC milliseconds
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST affected by commands
  -N, --nohz_full       CPUs in nohz_full kernel command line will be affected
                        by operations
  -S CPU-SOCKET-LIST, --sockets CPU-SOCKET-LIST
                        CPU-SOCKET-LIST affected by commands
  -U, --no_uthreads     Operations will not affect user threads
  -K, --no_kthreads     Operations will not affect kernel threads
.TP
\fB tuna cpuset\fR
usage: tuna-cmd.py cpuset [-h] {create,list,destroy,move,show,status,modify,save,apply}

Manage CPU sets (cgroup v2). Cpusets provide fine-grained control over which CPUs processes can run on, with NUMA-aware memory node assignment and kernel-enforced isolation.

subcommands:
  {create,list,destroy,move,show,status,modify,save,apply}

.B tuna cpuset create
usage: tuna-cmd.py cpuset create [-h] -c CPU-LIST [-n NAME] [-i]
                                 [-m MEM-NODES]

Create a new cpuset with specified CPUs. Memory nodes are auto-detected from CPU topology unless specified manually.

required arguments:
  -c CPU-LIST, --cpus CPU-LIST
                        CPU-LIST to assign to the cpuset

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  Cpuset name (default: auto-generate tunaN)
  -i, --isolated        Set CPU partition to isolated (kernel-enforced exclusivity)
  -m MEM-NODES, --memory-nodes MEM-NODES
                        Memory nodes (default: auto-detect from CPUs, e.g., "0" or "0-1")

.B tuna cpuset list
usage: tuna-cmd.py cpuset list [-h] [-p PATTERN] [-v] [--show-empty]
                               [--no-recursive]

List cpusets. By default, empty cpusets (no CPUs assigned) are skipped.

optional arguments:
  -h, --help            show this help message and exit
  -p PATTERN, --pattern PATTERN
                        Filter by glob pattern (e.g., tuna*)
  -v, --verbose         Show detailed information (CPUs, tasks, partition type)
  --show-empty          Include cpusets with no CPUs assigned (default: skip empty)
  --no-recursive        Only search top-level cpusets

.B tuna cpuset destroy
usage: tuna-cmd.py cpuset destroy [-h] [-p PATTERN] [-f]
                                  [--include-empty] [--no-recursive]
                                  [NAME ...]

Destroy cpuset(s)

positional arguments:
  NAME                  Cpuset name(s) to destroy (one or more, OR use --pattern)

optional arguments:
  -h, --help            show this help message and exit
  -p PATTERN, --pattern PATTERN
                        Glob pattern to destroy multiple cpusets (e.g., tuna*)
  -f, --force           Migrate tasks to root cgroup before destroying
  --include-empty       When using --pattern, include cpusets with no CPUs assigned
  --no-recursive        Only destroy top-level cpusets when using --pattern

.B tuna cpuset move
usage: tuna-cmd.py cpuset move [-h] [-t THREAD-LIST] [-p PID-LIST] NAME

Move processes to a cpuset

positional arguments:
  NAME                  Cpuset name to move processes to

optional arguments:
  -h, --help            show this help message and exit
  -t THREAD-LIST, --threads THREAD-LIST
                        THREAD-LIST affected by commands (supports patterns)
  -p PID-LIST, --pids PID-LIST
                        Comma-separated list of PIDs to move

.B tuna cpuset show
usage: tuna-cmd.py cpuset show [-h] [--show-tasks] NAME

Show detailed information about a cpuset

positional arguments:
  NAME           Cpuset name to show

optional arguments:
  -h, --help     show this help message and exit
  --show-tasks   Show detailed list of tasks/processes

.B tuna cpuset status
usage: tuna-cmd.py cpuset status [-h] [-p PATTERN] [--show-empty]
                                 [--no-recursive]

Show system-wide cpuset overview with statistics

optional arguments:
  -h, --help            show this help message and exit
  -p PATTERN, --pattern PATTERN
                        Filter by glob pattern (e.g., tuna*)
  --show-empty          Include cpusets with no CPUs assigned (default: skip empty)
  --no-recursive        Only show top-level cpusets

.B tuna cpuset modify
usage: tuna-cmd.py cpuset modify [-h] [--add-cpus CPU-LIST]
                                 [--remove-cpus CPU-LIST] [-m MEM-NODES]
                                 [--isolated | --no-isolated]
                                 NAME

Modify an existing cpuset without destroying it

positional arguments:
  NAME                  Cpuset name to modify

optional arguments:
  -h, --help            show this help message and exit
  --add-cpus CPU-LIST   CPUs to add to the cpuset (e.g., 4-7 or 4,5,6,7)
  --remove-cpus CPU-LIST
                        CPUs to remove from the cpuset (e.g., 0-1 or 0,1)
  -m MEM-NODES, --memory-nodes MEM-NODES
                        Set memory nodes (e.g., "0" or "0-1")
  --isolated            Set CPU partition to isolated
  --no-isolated         Set CPU partition to member (not isolated)

.B tuna cpuset save
usage: tuna-cmd.py cpuset save [-h] [filename]

Save cpuset configuration to YAML profile

positional arguments:
  filename    Output YAML file. Default path depends on execution context:
              ./cpuset-profile.yaml when running from development (tuna-cmd.py)
              /etc/tuna/cpuset-profile.yaml when running from production (tuna)

optional arguments:
  -h, --help  show this help message and exit

.B tuna cpuset apply
usage: tuna-cmd.py cpuset apply [-h] [-v] [filename]

Apply cpuset configuration from YAML profile

positional arguments:
  filename       Input YAML file. Default path depends on execution context:
                 ./cpuset-profile.yaml when running from development (tuna-cmd.py)
                 /etc/tuna/cpuset-profile.yaml when running from production (tuna)

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  Print detailed progress messages

.IP \fIModifiers\fR
.TP
\fB\-c\fR, \fB\-\-cpus\fR=\fICPU\-LIST\fR
CPU\-LIST affected by commands. Requires a CPU number, a range, or a comma-separated list of CPU numbers.
.TP
\fB\-S\fR, \fB\-\-sockets\fR=\fICPU\-SOCKET\-LIST\fR
CPU\-SOCKET\-LIST affected by commands. Requires a socket number or a comma-separated list of socket numbers.
.TP
\fB\-t\fR, \fB\-\-threads\fR=\fITHREAD\-LIST\fR
THREAD\-LIST affected by commands. Requires a thread number or thread name, or a comma-separated list of thread numbers and/or names. Thread names may contain wildcards. Be sure to quote or escape any wildcard specifications.
.TP
\fB\-q\fR, \fB\-\-irqs\fR=\fIIRQ\-LIST\fR
IRQ\-LIST affected by commands. Requires an IRQ number or IRQ user name, or a comma-separated list of IRQ numbers and/or user names. IRQ user names may contain wildcards. Be sure to quote or escape any wildcard specifications.
.SH USAGE EXAMPLES
.SS CPU Affinity Examples
If for instance the Ethernet NICs have multiple queues for both receive and transmit, each with its own IRQ, the Ethernet IRQs can be associated with a CPU socket:
.TP
.B tuna isolate -S 2
.TP
.B tuna spread -q 'eth*' -S 2

Move everything off the CPUs in socket 2, then spread the IRQs for the Ethernet devices across those same CPUs.

.SS Cpuset Examples
Create an isolated cpuset for real-time workloads:
.TP
.B tuna cpuset create -c 2-5 -n rt_workload -i

Create a cpuset named 'rt_workload' with CPUs 2-5, set to isolated partition. Memory nodes are auto-detected from CPU topology.

.TP
.B tuna run --cpuset rt_workload -p FIFO:80 'my_rt_app'

Launch a real-time application in the rt_workload cpuset with FIFO scheduler and priority 80.

.TP
Isolate CPUs using cpusets (more powerful than traditional affinity):
.TP
.B tuna isolate -c 4-7 --cpuset my_isolated --cpuset-housekeeping my_hk 0-3

Isolate CPUs 4-7 by creating 'my_isolated' cpuset with kernel-enforced exclusivity (partition=isolated), and move all existing processes to 'my_hk' cpuset on CPUs 0-3 (partition=member).

.TP
.B tuna move --cpuset rt_workload -t 'kworker/*'

Move all kworker threads to the rt_workload cpuset.

.TP
.B tuna show_threads --cpuset rt_workload

Show only processes running in the rt_workload cpuset.

.TP
.B tuna cpuset modify rt_workload --add-cpus 6-7

Add CPUs 6-7 to the rt_workload cpuset without disrupting running processes.

.TP
.B tuna cpuset status

Display system-wide overview of all cpusets with statistics.

.TP
.B tuna cpuset save /etc/tuna/my-rt-config.yaml

Save current cpuset configuration to a YAML profile. When running the installed version (tuna), the default path is /etc/tuna/cpuset-profile.yaml. When running from development (tuna-cmd.py), it defaults to ./cpuset-profile.yaml in the current directory.

.TP
.B tuna cpuset apply /etc/tuna/my-rt-config.yaml

Apply a previously saved cpuset configuration from a YAML profile. This recreates all cpusets defined in the profile with their CPU assignments, memory nodes, and partition settings.