[src/trunk]: src/share/man/man4 systrace device documentation.

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/42001cb13148
branches:  trunk
changeset: 532892:42001cb13148
user:      christos <christos%NetBSD.org@localhost>
date:      Mon Jun 17 16:31:50 2002 +0000

description:
systrace device documentation.

diffstat:

 share/man/man4/systrace.4 |  234 ++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 234 insertions(+), 0 deletions(-)

diffs (238 lines):

diff -r b29029849f7c -r 42001cb13148 share/man/man4/systrace.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/systrace.4 Mon Jun 17 16:31:50 2002 +0000
@@ -0,0 +1,234 @@
+.\"    $NetBSD: systrace.4,v 1.1 2002/06/17 16:31:50 christos Exp $
+.\"    $OpenBSD: systrace.4,v 1.2 2002/06/03 15:44:17 mpech Exp $
+.\"
+.\" Copyright (c) 2002 CubeSoft Communications, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistribution of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Neither the name of CubeSoft Communications, nor the names of its
+.\"    contributors may be used to endorse or promote products derived from
+.\"    this software without specific prior written permission.
+.\" 
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd May 26, 2002
+.Dt SYSTRACE 4
+.Os
+.Sh NAME
+.Nm systrace
+.Nd enforce and generate policies for system calls
+.Sh SYNOPSIS
+.Cd "pseudo-device systrace 1"
+.Sh DESCRIPTION
+.Nm
+attaches to processes and enforces policies for system calls.
+A pseudo-device,
+.Pa /dev/systrace ,
+allows userland processes to control the behavior of
+.Nm
+through an
+.Xr ioctl 2
+interface.
+.Sh SYSTEM CALL POLICIES
+.Nm
+can assign the following policies to system calls:
+.Bl -tag -enum -width "xxxxxx"
+.It SYSTR_POLICY_ASK
+Send a message of the type
+.Dv SYSTR_MSG_ASK ,
+and put the process to sleep until a
+.Dv STRIOCANSWER
+.Xr ioctl 2
+is made.
+.It SYSTR_POLICY_PERMIT
+Immediately allow the system call.
+.It SYSTR_POLICY_NEVER
+Immediately return an error code.
+.El
+.Sh SYSTRACE MESSAGES
+A
+.Xr read 2
+operation on the
+.Nm
+pseudo-device will block if there are no pending messages, or
+return the following structure:
+.Bd -literal
+struct str_message {
+       int32_t msg_type;
+#define SYSTR_MSG_ASK  1
+#define SYSTR_MSG_RES  2
+#define SYSTR_MSG_EMUL 3
+#define SYSTR_MSG_CHILD        4
+       pid_t msg_pid;
+       int16_t msg_policy;
+       union {
+               struct str_msg_emul msg_emul;
+               struct str_msg_ask msg_ask;
+               struct str_msg_child msg_child;
+       } msg_data;
+};
+
+struct str_msg_emul {
+       char emul[SYSTR_EMULEN];
+};
+
+struct str_msg_ask {
+       int32_t code;
+       int32_t argsize;
+       register_t args[SYSTR_MAXARGS];
+       register_t rval[2];
+       int32_t result;
+};
+
+struct str_msg_child {
+       pid_t new_pid;
+};
+.Ed
+.Sh IOCTL INTERFACE
+.Bl -tag -width "xxxxxx"
+.It Dv SYSTR_CLONE Fa "int"
+Return a
+.Nm
+file descriptor for
+further
+.Xr ioctl 2
+operations.
+.El
+.Nm
+supports the following
+.Xr ioctl 2
+command:
+.Bl -tag -width "xxxxxx"
+.It Dv STRIOCATTACH Fa "pid_t"
+Attach to a process, unless:
+.Bl -enum -compact -width 2n
+.It
+It's the process that's doing the attaching.
+.It
+It's a system process.
+.It
+It's being traced already.
+.It
+You do not own the process and you're not root.
+.It
+It's
+.Xr init 8 ,
+and the
+kernel was not compiled with
+.Cd option INSECURE .
+.El
+.It Dv STRIOCDETACH Fa "pid_t"
+Wake up a process if it is waiting for an answer, and detach from it.
+.It Dv STRIOCANSWER Fa "struct systrace_answer"
+Tell
+.Nm
+what to do with a system call that was assigned a policy of
+.Dv SYSTR_POLICY_ASK .
+.Bd -literal
+struct systrace_answer {
+       pid_t stra_pid;     /* PID of process being traced */
+       int32_t stra_policy;    /* Policy to assign */
+       int32_t stra_error;     /* Return value of denied syscall
+                              (will return EPERM if zero) */
+       int32_t stra_flags;
+#define        SYSTR_FLAGS_RESULT 0x0001    /* Report syscall result */
+};
+.Ed
+.It Dv STRIOCIO Fa "struct systrace_io"
+Copy data in/out of the process being traced.
+.Bd -literal
+struct systrace_io {
+       pid_t strio_pid;    /* PID of process being traced */
+       int32_t strio_ops;
+#define        SYSTR_READ      1
+#define        SYSTR_WRITE     2
+       void *strio_offs;
+       void *strio_addr;
+       size_t strio_len;
+};
+.Ed
+.It Dv STRIOCPOLICY Fa "struct systrace_policy"
+Manipulate the set of policies.
+.Bd -literal
+struct systrace_policy {
+       int strp_op;
+#define        SYSTR_POLICY_NEW        1    /* Allocate a new policy */
+#define        SYSTR_POLICY_ASSIGN     2    /* Assign policy to process */
+#define        SYSTR_POLICY_MODIFY     3    /* Modify an entry */
+       int32_t strp_num;
+       union {
+               struct {
+                       int16_t code;
+#define SYSTR_POLICY_ASK       0
+#define SYSTR_POLICY_PERMIT    1
+#define SYSTR_POLICY_NEVER     2
+                       int16_t policy;
+               } assign;
+               pid_t pid;
+               int32_t maxents;
+       } strp_data;
+#define strp_pid       strp_data.pid
+#define strp_maxents   strp_data.maxents
+#define strp_code      strp_data.assign.code
+#define strp_policy    strp_data.assign.policy
+};
+.Ed
+.Pp
+The
+.Dv SYSTR_POLICY_NEW
+operation allocates a new policy with all entries initialized to
+.Dv SYSTR_POLICY_ASK ,
+and returns the new policy number into
+.Va strp_num .
+The
+.Dv SYSTR_POLICY_ASSIGN
+operation attaches the policy identified by
+.Va strp_num
+to
+.Va strp_pid ,
+with a maximum of
+.Va strp_maxents
+entries.
+The
+.Dv SYSTR_POLICY_MODIFY
+operation changes the entry indexed by
+.Va strp_code
+to
+.Va strp_policy .
+.It Dv STRIOCGETCWD Fa "pid_t"
+Set the working directory of the current process to that of the
+named process.
+.It Dv STRIOCRESCWD
+Restore the working directory of the current process.
+.El
+.Sh FILES
+.Bl -tag -width "/dev/systrace" -compact
+.It Pa /dev/systrace
+system call tracing facility
+.El
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr read 2 ,
+.Xr options 4 ,
+.Xr securelevel 7
+.Sh HISTORY
+The
+.Nm
+facility first appeared in
+.Ox 3.2 .
+.\" .Sh BUGS
+.\" .Sh CAVEATS