STAP-SERVER(8)

🌸 STAP-SERVER — the stap-server manual, but make it cute 🌸

okay bestie, sit down, hydrate, because we're about to talk about stap-server, aka systemtap compile server management, and honestly? she's iconic. this is the System Manager's Manual page for STAP-SERVER(8) and we're doing it properly. no skimming. no skipping the "boring" bits (there are no boring bits, that's a lie we tell ourselves). 💅

---

✨ NAME ✨

stap-server — systemtap compile server management 🎀

---

🦋 SYNOPSIS 🦋

[ service ] stap-server { start | stop | restart | condrestart |
try-restart | force-reload | status } [ options ]

that's the whole vibe check right there. you pick an action, you optionally pass options, the server does her thing. periodt. 💖

---

💜 DESCRIPTION 💜

so, what is a systemtap compile server, you ask? bestie. she's a whole situation. a systemtap compile server listens for connections from stap clients on a secure SSL network port, and she accepts requests to run the stap front end. that's her job. that's her purpose. main character energy fr.

and the way she advertises herself?? each server announces her presence and her configuration on the local network using mDNS (avahi), which means clients can just... find her. automatically. no setup, no awkward "hey do you know where the server is" small talk. obsessed. ✨

the stap-server script aims to provide:

• management of systemtap compile servers as a service. 💁‍♀️
• convenient control over configured servers and individual (ad-hoc) servers. 🫶

---

🌈 ARGUMENTS 🌈

you must specify exactly one of the actions below. one. not zero. not two. one. okay? okay. 💖

• start — Start servers. the servers you specified get started. if you specified no server, then the configured servers are started. and if there are no servers configured at all? a server for the kernel release and architecture of the host is started. if a specified server is already started, this action is just... ignored for that server, no drama. but if a server fails to start, the whole action fails. 😭
• stop — Stop server(s). the specified servers get stopped. if you didn't specify one, all currently running servers are stopped. if a specified server isn't running, that's fine, the action is still successful for her. but if a server fails to stop, the action fails. 💀
• restart — Stop and restart servers. specified servers are stopped and restarted. no server specified? then all currently running servers get stopped and restarted. and if no servers are running at all, this behaves exactly like start. slay. 🔥
• condrestart — Stop and restart servers, but with ✨conditions✨. specified servers get stopped and restarted, but if a specified server isn't running, it is not started. no server specified? all currently running servers get stopped and restarted. and if none are running, none will be started. she's respectful like that. 🎀
• try-restart — this action is identical to condrestart. literally the same. twins. 👯‍♀️
• force-reload — Stop all running servers, reload config files, and restart the service as if start was specified. that's the whole thing. dramatic? maybe. effective? yes. 💅
• status — Print information about running servers. if you specified server(s), you get info about those. if not, you get info about all running servers. she's an open book. 📖

---

💖 OPTIONS 💖

these are the options that give you extra configuration and let you specify which servers get managed. buckle up, there's a bunch, and we're doing all of them. no cap. 🧚

• -c configfile — specifies a global configuration file in addition to the default global configuration file described below. this file gets processed after the default global configuration file. and if you pass -c more than once? only the last configuration file specified gets used. sorry to the earlier ones. 🙈
• -a architecture — specifies the target architecture of the server, and it's analogous to the -a option of stap. see the stap(1) manual page for more details. default architecture is the architecture of the host. 🏠
• -r kernel-release — specifies a target kernel release of the server, analogous to the -r option of stap. see the stap(1) manual page for more details. the default release is that of the currently running kernel. and here's the cute part: a server can handle multiple releases by specifying multiple -r flags. she's multitasking. 💅
• -I path — specifies an additional path to be searched by the server(s) for tapsets, analogous to the -I option of stap. see the stap(1) manual page for more details. 📂
• -R path — specifies the location of the systemtap runtime to be used by the server(s), analogous to the -R option of stap. see the stap(1) manual page for more details. ⭐
• -B options — specifies options to be passed to make when building systemtap modules, analogous to the -B option of stap. see the stap(1) manual page for more details. 🔨
• -i — a shortcut! this specifies a server that handles every release installed in /lib/modules/. that's it. that's the whole option. efficiency queen. 👑
• -n nickname — lets you specify a server configuration by nickname. here's how it goes: when -n is specified, a currently running server with the given nickname gets searched for. if no currently running server with that nickname is found, a server configuration with that nickname gets searched for in the configuration files for default servers, or the path configured in the global configuration file, or the configuration file specified by the -c option. if a server configuration for that nickname is found, then the -a, -r, -I, -R, -B and -u options for that server will be used as if they were specified on the command line. if no configuration with that nickname is found, and the action is start (or an action behaving like start — see ARGUMENTS), the server will be started with the given nickname. if no configuration with that nickname is found, and the action is not start (or an action behaving like start), it is an error. and finally: if a nickname is not specified for a server which is being started, its nickname will be its process id. so she names herself. iconic. 🎀
• -p pid — lets you specify a server configuration by process id. when -p is specified, a currently running server with the given process id gets searched for. if no such server is found, it is an error. if a server with the given process id is found, the -a, -r, -I, -R, -B and -u options for that server will be used as if they were specified on the command line. 🔍
• -u user-name — each systemtap compile server is normally run by the user name stap-server (for the initscript) or as the user invoking stap-server, unless otherwise configured (see FILES). this option specifies the user name used to run the server(s). the user name specified must be a member of the group stap-server. don't forget that part, bestie, it's important. 💜
• --log logfile — lets you specify a separate log file for each server. each --log option is added to a list, which gets applied, in turn, to each server specified. if you specify more servers than --log options, the default log file (see FILES) is used for the subsequent servers. 📝
• --port port-number — lets you specify a specific network port for each server. each --port option is added to a list, applied in turn to each server specified. if you specify more servers than --port options, a randomly selected port is used for the subsequent servers. surprise port!! 🎲
• --ssl certificate-db-path — lets you specify a separate NSS certificate database for each server. each --ssl option is added to a list, applied in turn to each server specified. if you specify more servers than --ssl options, the default certificate database (see FILES) is used for subsequent servers. 🔐
• --max-threads threads — lets you specify the maximum number of worker threads to handle concurrent requests. if threads == 0, each request will be handled on the main thread, serially. the default is the number of available processor cores. she's scalable, she's adaptable. 🧵
• --max-request-size size — lets you specify the maximum size of an uncompressed client request. the argument size is specified in bytes. the default is 50000 bytes. 📏
• --max-compressed-request size — lets you specify the maximum size of a compressed client request. the argument size is specified in bytes. the default is 5000 bytes. 🗜️

---

🌸 CONFIGURATION 🌸

configuration files let us do two very important things:

• specify global configuration of logging, server configuration files, status files and other global parameters. ⚙️
• specify which servers are to be started by default. 🚀

💖 Global Configuration 💖

the Global Configuration file contains variable assignments used to configure the overall operation of the service. each line beginning with a # character is ignored. all other lines must be of the form VARIABLE=VALUE.

heads up bestie: this is not a shell script. the entire contents of the line after the = will be assigned as-is to the variable. no expansion, no tricks. as-is. 💅

the following variables may be assigned:

• CONFIG_PATH — specifies the absolute path of the directory containing the default server configurations. 📁
• STAT_PATH — specifies the absolute path of the running server status directory. 📊
• LOG_FILE — specifies the absolute path of the log file. 📝
• STAP_USER — specifies the userid which will be used to run the server(s) (default: for the initscript stap-server, otherwise the user running stap-server). 👤

here's an example of a Global Configuration file, verbatim, do not touch:

CONFIG_PATH=~<user>/my-stap-server-configs
LOG_FILE=/tmp/stap-server/log

---

and that's where part 1 ends, bestie — because there's more of this page and we're not even close to done. don't go anywhere. 💖

💖 Individual Server Configuration 💖

Okay bestie, so every individual server config file is basically setting up one server. It gets started when you don't name a specific server for the start action, or for any action that acts like start (peep ARGUMENTS for that 👀). Each config file is just a pile of variable assignments that describe a single server. That's it. That's the whole vibe.

A few ground rules before we go off:

• Any line starting with a # character? Ignored. Bye. Don't care. Not reading it.
• Every other line has to look like VARIABLE=VALUE.
• This is NOT a shell script, okay? Not even a little. The entire contents of the line after the = get assigned as-is to the variable. No expansion, no funny business. What you type is what you get. Periodt.

Also, every config file must have a filename suffix of .conf. Check stappaths(7) for where these files live by default, and know that this default location can be overridden in the global configuration file using the -c option (see OPTIONS).

---

Here are all the variables you can assign, and yes we're going through every single one because we're thorough like that ✨:

• ARCH — says what the target architecture is for this server. It's the buddy of the -a option (see OPTIONS). If ARCH isn't set, it just uses the host's architecture.
• RELEASE — says what kernel release this server is for, and it matches up with the -r option (see OPTIONS). Leave RELEASE unset and it'll use the release of the kernel that's actually running on the host.
• BUILD — passes options along to the make process that systemtap uses to build kernel modules. It's an array variable, and each element is basically a -B option (see OPTIONS). Writing BUILD=STRING clears the whole array and sets the first element to STRING. Writing BUILD+=STRING tacks STRING on as an extra element. Chef's kiss, very tidy.
• INCLUDE — a list of directories the server should search for tapsets. Also an array variable, each element = a -I option (see OPTIONS). INCLUDE=PATH clears the array and sets the first element to PATH. INCLUDE+=PATH adds PATH as another element.
• RUNTIME — the directory holding the systemtap runtime code this server should use. Matches the -R option (see OPTIONS).
• USER — the user name to run this server as. Matches the -u option (see OPTIONS).
• NICKNAME — the nickname used to refer to this server. Matches the -n option (see OPTIONS).
• LOG — where the log file for this server lives. Matches the --log option (see OPTIONS).
• PORT — the network port this server uses. Matches the --port option (see OPTIONS).
• SSL — the location of the NSS certificate database this server uses. Matches the --ssl option (see OPTIONS).
• MAXTHREADS — the max number of worker threads for handling concurrent requests on this server. Matches the --max-threads option (see OPTIONS).
• MAXREQSIZE — the max size of an uncompressed client request for this server, matching the --max-request-size option (see OPTIONS).
• MAXCOMPRESSEDREQ — the max size of a compressed client request for this server, matching the --max-compressed-request option (see OPTIONS).

---

Okay now the fun part, examples of what these files actually look like 💅

Here's a server config file, iconic and minimal:

ARCH=
USER=
RELEASE=
NICKNAME=native

And the way that works: by leaving the ARCH, USER, and RELEASE fields blank, they just default to the current arch and release and use the default user. Slay, no notes.

A more specific one:

ARCH=i386
RELEASE=2.6.18-128.el5
PORT=5001
LOG=/path/to/log/file

And here's the complicated one, main character energy fr:

USER=serveruser
RELEASE=/kernels/2.6.18-92.1.18.el5/build
INCLUDE=/mytapsets
INCLUDE+=/yourtapsets
BUILD='VARIABLE1=VALUE1 VARIABLE2=VALUE2'
DEFINE=STP_MAXMEMORY=1024
DEFINE+=DEBUG_TRANS
RUNTIME=/myruntime
NICKNAME=my-server
SSL=/path/to/NSS/certificate/database

---

🔐 SERVER AUTHENTICATION 🔐

So the security of that SSL network connection between client and server? It lives and dies by proper management of server certificates. That's the whole game.

Here's the tea: you can't just automatically figure out whether a given systemtap compile server is trustworthy, not without a trusted certificate authority handing out systemtap compile server certificates. And that's just... not practical for everyday use, bestie. So instead, clients authenticate servers against their own database of trusted server certificates. In this context, making a server "trusted" by a client literally means adding that server's certificate to the client's database of trusted servers. That's it, that's the definition.

For the stap-server initscript, on the local host, this is handled automatically ✨. When the systemtap-server package is installed, the server's certificate for the default user (stap-server) gets automatically generated and installed. Which means servers started by the stap-server initscript, with the default user, are automatically trusted by clients on the local host — both as an SSL peer and as a systemtap module signer. Two for one, we love that.

And more good news: when stap is invoked by an unprivileged user (not root, not a member of the group stapdev, but a member of the group stapusr and possibly the group stapsys), the options --use-server and --privilege are automatically added to whatever options were specified. So unprivileged users on the local host can use a local server in unprivileged mode with zero extra setup and zero extra options. Nothing. Just vibes.

Normal users — the ones in none of the SystemTap groups — can also use compile-servers through the --use-server and --privilege options. But obviously they won't be able to load the module 😭 (the -p4 option can be used to stop short of loading, if that's what you want).

Now, if you wanna use a server running on another host? That server's certificate must be installed on the client's host. See the --trust-servers option in the stap(1) manual page for more details, and README.unprivileged in the systemtap sources for more details. iykyk.

---

🌈 EXAMPLES 🌈

See the stapex(3stap) manual page for a whole collection of sample systemtap scripts, if you want inspiration.

To start the configured servers — or the default server, if none are configured:

$ [ service ] stap-server start

To start a server that handles all kernel versions installed in /lib/modules:

$ [ service ] stap-server start -i

To obtain information about the running server(s):

$ [ service ] stap-server status

To start a server like another one, except targeting a different architecture, by referencing the first server's nickname:

$ [ service ] stap-server start -n NICKNAME -a ARCH

To start a server for a kernel release that's not installed (cross-compiling):

$ [ service ] stap-server start -a ARCH -r /BUILDDIR

To stop one of the servers by referencing its process id (you get that from running stap-server status):

$ [ service ] stap-server stop -p PID

To run a script using a compile server:

$ stap SCRIPT --use-server

To run a script as an unprivileged user using a compile server:

$ stap SCRIPT

To stop all running servers:

$ [ service ] stap-server stop

To restart servers after a global configuration change and/or when default servers have been added, changed, or removed:

$ [ service ] stap-server force-reload

---

🛡️ SAFETY AND SECURITY 🛡️

Okay, serious voice for a sec. Systemtap is an administrative tool. It exposes kernel internal data structures and potentially private user information. See the stap(1) manual page for additional info on safety and security.

And as a network server, stap-server should be activated with care, so you limit the potential effects of bugs or mischievous users. Think of the following prophylactic measures as your little safety checklist 🎀:

1. Run stap-server as an unprivileged user, never as root.

When invoked as a service (i.e. service stap-server ...), each server is run, by default, as the user stap-server. When invoked directly (i.e. stap-server ...), each server is run, by default, as the invoking user. In each case, another user may be selected by using the -u option on invocation, by specifying STAP_USER=username in the global configuration file, or by specifying USER=username in an individual server configuration file. The invoking user must have authority to run processes as another user. See CONFIGURATION.

The selected user must have write access to the server log file. The location of the server log file may be changed by setting LOG_FILE=path in the global configuration file. See CONFIGURATION.

The selected user must have read/write access to the directory containing the server status files. The location of the server status files may be changed by setting STAT_PATH=path in the global configuration file. See CONFIGURATION.

The selected user must have read/write access to the uprobes.ko build directory and its files.

Neither form of stap-server will run if the selected user is root. Like, it just won't. Don't try it.

2. Run stap-server requests with resource limits that impose maximum cpu time, file size, memory consumption, in order to bound the effects of processing excessively large or bogus inputs.

When the user running the server is stap-server, each server request is run with limits specified in ~stap-server/.systemtap/rc — otherwise, no limits are imposed. 😬

3. Run stap-server with a TMPDIR environment variable that points to a separate and/or quota-enforced directory, in order to prevent filling up of important filesystems.

The default TMPDIR is /tmp/.

4. Activate network firewalls to limit stap client connections to relatively trustworthy networks.

For automatic selection of servers by clients, avahi must be installed on both the server and client hosts and mDNS messages must be allowed through the firewall.

---

The systemtap compile server and its related utilities use the Secure Socket Layer (SSL) as implemented by Network Security Services (NSS) for network security. NSS is also used for the generation and management of certificates. The related certificate databases must be protected in order to maintain the security of the system. Use of the utilities provided will help to ensure that the proper protection is maintained. And the systemtap client will check for proper access permissions before making use of any certificate database. Responsible king behavior 👑

📁 FILES 📁

ok so where do all the important files actually live?? bestie they're all listed out for you in the stappaths(7) manual page 💖 like every important file and its corresponding path, all in one place. go look there, that's the map 🗺️✨

---

👀 SEE ALSO 👀

the friend group of this manpage, fr fr:

• stap(1)
• staprun(8)
• stapprobes(3stap)
• stappaths(7)
• stapex(3stap)
• avahi
• ulimit(1)
• NSS

go read them, they're all serving 💅

---

🐛 BUGS 🐛

found something cursed? 😭 no worries, it happens to the best of us. hit up the Bugzilla link on the project web page, or just slide into our mailing list 🫶

• http://sourceware.org/systemtap/
• <systemtap@sourceware.org>

that's it, that's the whole vibe — report it, we'll handle it 💖

---

and that's a wrap on STAP-SERVER(8) bestie!! 🎀 you made it to the very end, main character energy for real 👑 the footer down there is just the page name with its version and date stamped on it like a little signature, so consider this my cute sign-off instead: go build something iconic with your server, stay safe with those privileges, and ily 💜✨🦋