summaryrefslogtreecommitdiffstats
path: root/stap-client.8.in
blob: f4ca86f631ba9fddb5d351b666de40f67f8a0391 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
.\" -*- nroff -*-
.TH STAP-CLIENT 8 @DATE@ "Red Hat"
.SH NAME
stap\-client \- systemtap client

.SH SYNOPSIS

.br
.B stap\-client
[
.B \-\-server=\fIHOSTNAME\fR|\fIIP_ADDRESS\fR[\fB:\fIPORT\fR]
]
[
.B \-\-ssl=\fIDIRNAME
]
[
.I ARGUMENTS
]

.SH DESCRIPTION

A systemtap compile server listens for connections from clients
(\fIstap\-client\fR)
on a secure SSL network port and accepts requests to run the
.I stap
front end. Each server advertises its presence and configuration on the local
network using mDNS (\fIavahi\fR) allowing for automatic detection by clients.

.PP
The
.I stap\-client
program is analogous to the
.I stap
front end except that it attempts to find a compatible systemtap server on the
local network and then attempts to use that server for actions related to
passes 1 through 4. Pass 5 actions, if requested, are performed on the local
host using
.IR staprun .
Upon successful completion, the exit code is 0. Otherwise the exit code
is 1.

.SH OPTIONS
.PP
In addition to the options accepted by the
.I stap
front end,
.I stap\-client
accepts the following:

.TP
.B \-\-server=\fIHOSTNAME\fR|\fIIP_ADDRESS\fR[\fB:\fIPORT\fR]
This option instructs
.I stap\-client
to use the named server instead of looking for one automatically. The server may
be specified using a valid host name or ip address. If no port is specified,
then
.I stap\-client
searches for the server among the servers on the specified host which are
advertising their presence on the
local network and uses the port which is being advertised. This is useful for
connecting to a specific server on the local network. If a port is specified,
then
.I stap\-client
will attempt to connect to the named host on the specified port. This is useful
for connecting to non\-local servers. If
.B \-\-server
is specified,
.I stap\-client
will make no attempt to contact other servers. If more than one
.B \-\-server
option is specified,
.I stap\-client
will attempt to use the servers in the order specified.

.TP
.B \-\-ssl=\fIDIRNAME
.I stap\-client
uses certificate databases in default locations (see
.I SERVER AUTHENTICATION
below) in order to authenticate each server which is contacted. The
.B \-\-ssl
option is used to specify additional databases to search. Databases specified
using
.B \-\-ssl
are searched before the default databases. If more than one
.B \-\-ssl
option is specified, then the databases are searched in the order specified on
the command line followed by the default locations.

.SH ARGUMENTS
The
.I stap\-client
program accepts the same arguments as
.I stap\fP.
See \fIstap\fP(1) for details.

.SH SERVER AUTHENTICAION
The security of the SSL network connection between the client and server
depends on the proper
management of server certificates.

.PP
The trustworthiness of a given systemtap server can not be determined
automatically without a trusted certificate authority issuing systemtap server
certificates. This is
not practical in everyday use and so, clients must authenticate servers
against their own database of trusted server certificates. In this context,
establishing a given server as trusted by a given client means adding
that server\[aq]s certificate to the
client\[aq]s database of trusted servers.

.PP
For the \fIstap\-server\fR service, on the local host, this is handled
automatically.
When the \fIsystemtap\-server\fR package is installed, the server\[aq]s
certificate for the default user (\fIstap\-server\fR) is automatically
generated and installed. This means that servers started by the
\fIstap\-server\fR service,
with the default user, are automatically trusted by clients on the local
host.

.PP
In order to use a server running on another host, that server\[aq]s certificate
must be installed on the client\[aq]s host.
See the
.IR stap\-authorize\-server\-cert (8)
manual page for more details.

.PP
The trustworthiness of other servers may also be asserted
for the duration of one invocation of \fIstap\-client\fR
by using the
.B \-\-ssl
option one or more times (see
.I OPTIONS
above). Servers whose certificates are contained in the additional databases
will be considered to be trusted for that invocation of the client.

.SH UNPRIVILEGED USERS
One purpose of the systemtap client and server is to provide a secure
compilation environment and trusted signer for allowing unprivileged users
(members of the group \fIstapusr\fR) to load systemtap modules generated from
scripts which use only a safe subset of systemtap\[aq]s capabilities.

.PP
When the \fB\-\-unprivileged\fR option is used on an invocation of
\fIstap\-client\fR, the server will pass it on to \fIstap\fR which will
check to ensure that the script is safe to run for unprivileged users. If so,
the server will also sign the resulting module, making it loadable by an
unprivileged user.

.SH EXAMPLES
See the 
.IR stapex (3stap)
manual page for a collection of sample scripts.
.PP
Here are some examples of how to use
.IR stap\-client .
.PP
To compile and execute a simple example using an automatically discovered
server on the local network
.PP
.B \& $ stap\-client \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& Hello World!
.PP
To compile and execute a simple example using a server on a specific host
on the local network
.PP
.B \& $ stap\-client \-\-server=\fIHOSTNAME\fP \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& Hello World!
.PP
To compile and execute a simple example using a specific server
.PP
.B \& $ stap\-client \-\-server=\fIHOSTNAME\fP:\fIPORT\fP \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& Hello World!
.PP
To search additional certificate databases in order to compile and execute a
simple example
.PP
.B \& $ stap\-client \-\-ssl=\fIDIRNAME\fP \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& Hello World!

.SH SAFETY AND SECURITY
Systemtap is an administrative tool.  It exposes kernel internal data
structures and potentially private user information.  See the 
.IR stap (1)
manual page for additional information on safety and security.

.PP
The systemtap server and its related utilities use the Secure Socket Layer
(SSL) as implemented by Network Security Services (NSS)
for network security. The NSS tool
.I certutil
is used for the generation 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. The systemtap client will check for proper
access permissions before making use of any certificate database.

.SH FILES
.TP
@sysconfdir@/systemtap/ssl/client/
Public (root\[aq]s) client side certificate database.

.TP
~/.systemtap/ssl/client/
User\[aq]s private client side certificate database.

.TP
/var/lib/stap\-server/.systemtap/ssl/server/stap.cert
Server certificate for servers started by the \fIstap\-server\fR service.

.SH SEE ALSO
.IR stap (1),
.IR staprun (8),
.IR stap\-server (8),
.IR stap\-authorize\-server\-cert (8),
.IR stapprobes (3stap),
.IR stapfuncs (3stap),
.IR stapex (3stap),
.IR NSS ,
.IR certutil

.SH BUGS
Use the Bugzilla link of the project web page or our mailing list.
.nh
.BR http://sources.redhat.com/systemtap/ ", " <systemtap@sources.redhat.com> .
.hy