1STAP-CLIENT(8) System Manager's Manual STAP-CLIENT(8)
2
6 stap-client - systemtap client
7
10 stap-client [ --server=HOSTNAME|IP_ADDRESS[:PORT] ] [ --ssl=DIRNAME ] [
11 ARGUMENTS ]
12
15 A systemtap compile server listens for connections from clients
16 (stap-client) on a secure SSL network port and accepts requests to run
17 the stap front end. Each server advertises its presence and configura‐
18 tion on the local network using mDNS (avahi) allowing for automatic
19 detection by clients.
20 The stap-client program is analogous to the stap front end except that
23 it attempts to find a compatible systemtap server on the local network
24 and then attempts to use that server for actions related to passes 1
25 through 4. Pass 5 actions, if requested, are performed on the local
26 host using staprun. Upon successful completion, the exit code is 0.
27 Otherwise the exit code is 1.
28
31 In addition to the options accepted by the stap front end, stap-client
32 accepts the following:
33 --server=HOSTNAME|IP_ADDRESS[:PORT]
36 This option instructs stap-client to use the named server
37 instead of looking for one automatically. The server may be
38 specified using a valid host name or ip address. If no port is
39 specified, then stap-client searches for the server among the
40 servers on the specified host which are advertising their pres‐
41 ence on the local network and uses the port which is being
42 advertised. This is useful for connecting to a specific server
43 on the local network. If a port is specified, then stap-client
44 will attempt to connect to the named host on the specified port.
45 This is useful for connecting to non-local servers. If --server
46 is specified, stap-client will make no attempt to contact other
47 servers. If more than one --server option is specified,
48 stap-client will attempt to use the servers in the order speci‐
49 fied.
50 --ssl=DIRNAME
53 stap-client uses certificate databases in default locations (see
54 SERVER AUTHENTICATION below) in order to authenticate each
55 server which is contacted. The --ssl option is used to specify
56 additional databases to search. Databases specified using --ssl
57 are searched before the default databases. If more than one
58 --ssl option is specified, then the databases are searched in
59 the order specified on the command line followed by the default
60 locations.
61
64 The stap-client program accepts the same arguments as stap. See
65 stap(1) for details.
66
69 The security of the SSL network connection between the client and
70 server depends on the proper management of server certificates.
71 The trustworthiness of a given systemtap server can not be determined
74 automatically without a trusted certificate authority issuing systemtap
75 server certificates. This is not practical in everyday use and so,
76 clients must authenticate servers against their own database of trusted
77 server certificates. In this context, establishing a given server as
78 trusted by a given client means adding that server's certificate to the
79 client's database of trusted servers.
80 For the stap-server service, on the local host, this is handled auto‐
83 matically. When the systemtap-server package is installed, the
84 server's certificate for the default user (stap-server) is automati‐
85 cally generated and installed. This means that servers started by the
86 stap-server service, with the default user, are automatically trusted
87 by clients on the local host.
88 In order to use a server running on another host, that server's cer‐
91 tificate must be installed on the client's host. See the stap-autho‐
92 rize-server-cert(8) manual page for more details.
93 The trustworthiness of other servers may also be asserted for the dura‐
96 tion of one invocation of stap-client by using the --ssl option one or
97 more times (see OPTIONS above). Servers whose certificates are con‐
98 tained in the additional databases will be considered to be trusted for
99 that invocation of the client.
100
103 One purpose of the systemtap client and server is to provide a secure
104 compilation environment and trusted signer for allowing unprivileged
105 users (members of the group stapusr) to load systemtap modules gener‐
106 ated from scripts which use only a safe subset of systemtap's capabili‐
107 ties.
108 When the --unprivileged option is used on an invocation of stap-client,
111 the server will pass it on to stap which will check to ensure that the
112 script is safe to run for unprivileged users. If so, the server will
113 also sign the resulting module, making it loadable by an unprivileged
114 user.
115
118 See the stapex(3stap) manual page for a collection of sample scripts.
119 Here are some examples of how to use stap-client.
121 To compile and execute a simple example using an automatically discov‐
123 ered server on the local network
124 $ stap-client -e 'probe begin { printf("Hello World!0); exit() }'
126 Hello World!
127 To compile and execute a simple example using a server on a specific
129 host on the local network
130 $ stap-client --server=HOSTNAME -e 'probe begin { printf("Hello
132 World!0); exit() }'
133 Hello World!
134 To compile and execute a simple example using a specific server
136 $ stap-client --server=HOSTNAME:PORT -e 'probe begin { printf("Hello
138 World!0); exit() }'
139 Hello World!
140 To search additional certificate databases in order to compile and exe‐
142 cute a simple example
143 $ stap-client --ssl=DIRNAME -e 'probe begin { printf("Hello World!0);
145 exit() }'
146 Hello World!
147
150 Systemtap is an administrative tool. It exposes kernel internal data
151 structures and potentially private user information. See the stap(1)
152 manual page for additional information on safety and security.
153 The systemtap server and its related utilities use the Secure Socket
156 Layer (SSL) as implemented by Network Security Services (NSS) for net‐
157 work security. The NSS tool certutil is used for the generation of cer‐
158 tificates. The related certificate databases must be protected in order
159 to maintain the security of the system. Use of the utilities provided
160 will help to ensure that the proper protection is maintained. The sys‐
161 temtap client will check for proper access permissions before making
162 use of any certificate database.
163
166 ~/.systemtap/ssl/client/
167 User's private client side certificate database.
168 /var/lib/stap-server/.systemtap/ssl/server/stap.cert
171 Server certificate for servers started by the stap-server ser‐
172 vice.
173
176 stap(1), stappaths(7), staprun(8), stap-server(8), stap-autho‐
177 rize-server-cert(8), stapprobes(3stap), stapfuncs(3stap),
178 stapex(3stap), NSS, certutil
179
182 Use the Bugzilla link of the project web page or our mailing list.
183 http://sources.redhat.com/systemtap/, <systemtap@sources.redhat.com>.
184 STAP-CLIENT(8)