.\" -*- 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/ ", " . .hy