path: root/usr/src/man/man1m/sac.1m

'\" te
.\" Copyright 1989 AT&T
.\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SAC 1M "Apr 21, 2009"
.SH NAME
sac \- service access controller
.SH SYNOPSIS
.LP
.nf
\fBsac\fR \fB-t\fR \fIsanity_interval\fR
.fi

.LP
.nf
\fB/usr/lib/saf/sac\fR
.fi

.SH DESCRIPTION
.sp
.LP
The Service Access Controller (SAC) is the overseer of the server machine. It
is started when the server machine enters multiuser mode. The \fBSAC\fR
performs several important functions as explained below.
.SS "Customizing the SAC Environment"
.sp
.LP
When \fBsac\fR is invoked, it first looks for the per-system configuration
script \fB/etc/saf/_sysconfig\fR. \fBsac\fR interprets \fB_sysconfig\fR to
customize its own environment. The modifications made to the \fBSAC\fR
environment by \fB_sysconfig\fR are inherited by all the children of the
\fBSAC.\fR This inherited environment may be modified by the children.
.SS "Starting Port Monitors"
.sp
.LP
After it has interpreted the \fB_sysconfig\fR file, the \fBsac\fR reads its
administrative file \fB/etc/saf/_sactab\fR. \fB_sactab\fR specifies which port
monitors are to be started. For each port monitor to be started, \fBsac\fR
forks a child (see \fBfork\fR(2)) and creates a \fButmpx\fR entry with the
\fBtype\fR field set to \fBLOGIN_PROCESS\fR. Each child then interprets its
per-port monitor configuration script \fB/etc/saf/\fR\fIpmtag\fR\fB/_config\fR
, if the file exists. These modifications to the environment  affect the port
monitor and will be inherited by all its children. Finally, the child process
\fBexec\fRs the port monitor, using the command found in the \fB_sactab\fR
entry.  (See \fBsacadm\fR; this is the command given with the \fB-c\fR option
when the port monitor is added to the system.)
.SS "Polling Port Monitors to Detect Failure"
.sp
.LP
The \fB-t\fR option sets the frequency with which \fBsac\fR polls the port
monitors on the system. This time may also be thought of as half of the maximum
latency required to detect that a port monitor has failed and that recovery
action is necessary.
.SS "Administrative functions"
.sp
.LP
The Service Access Controller represents the administrative point of control
for port monitors. Its administrative tasks are explained below.
.sp
.LP
When queried (\fBsacadm\fR with either \fB-l\fR or \fB-L\fR), the Service
Access Controller returns the status  of the port monitors specified, which
\fBsacadm\fR prints on the standard output. A port monitor may be in one of six
states:
.sp
.ne 2
.na
\fB\fBENABLED\fR\fR
.ad
.RS 14n
The port monitor is currently running and is accepting connections. See
\fBsacadm\fR(1M) with the \fB-e\fR option.
.RE

.sp
.ne 2
.na
\fB\fBDISABLED\fR\fR
.ad
.RS 14n
The port monitor is currently running and is not accepting connections. See
\fBsacadm\fR with the \fB-d\fR option, and see \fBNOTRUNNING\fR, below.
.RE

.sp
.ne 2
.na
\fB\fBSTARTING\fR\fR
.ad
.RS 14n
The port monitor is in the process of starting up. \fBSTARTING\fR is an
intermediate state  on the way to \fBENABLED\fR or \fBDISABLED\fR.
.RE

.sp
.ne 2
.na
\fB\fBFAILED\fR\fR
.ad
.RS 14n
The port monitor was unable to start and remain running.
.RE

.sp
.ne 2
.na
\fB\fBSTOPPING\fR\fR
.ad
.RS 14n
The port monitor has been manually terminated but has not completed its
shutdown procedure. \fBSTOPPING\fR is an intermediate state on the way to
\fBNOTRUNNING\fR.
.RE

.sp
.ne 2
.na
\fB\fBNOTRUNNING\fR\fR
.ad
.RS 14n
The port monitor is not currently running. (See \fBsacadm\fR with \fB-k\fR.)
This is the normal "not running" state. When a port monitor is killed, all
ports it was monitoring are inaccessible.  It is not possible for an external
user to tell whether a port is not being monitored or the system is down. If
the port monitor is not killed but is in the \fBDISABLED\fR state, it may be
possible (depending on the port monitor being used) to write a message on the
inaccessible port telling the user who is trying to access the port that it is
disabled. This is the advantage of having a \fBDISABLED\fR state as well as the
\fBNOTRUNNING\fR state.
.RE

.sp
.LP
When a port monitor terminates, the \fBSAC\fR removes the \fButmpx\fR entry for
that port monitor.
.sp
.LP
The \fBSAC\fR receives all requests to enable, disable, start, or stop port
monitors and  takes the appropriate action.
.sp
.LP
The \fBSAC\fR is responsible for restarting port monitors that terminate.
Whether or not the \fBSAC\fR will restart a given port monitor depends on two
things:
.RS +4
.TP
.ie t \(bu
.el o
The restart count specified for the port monitor when the port monitor was
added by \fBsacadm\fR; this information is included in
\fB/etc/saf/\fR\fIpmtag\fR\fB/_sactab.\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
The number of times the port monitor has already been restarted.
.RE
.SH SECURITY
.sp
.LP
\fBsac\fR uses \fBpam\fR(3PAM) for session management.  The \fBPAM\fR
configuration policy, listed through \fB/etc/pam.conf\fR, specifies the session
management module to be used for \fBsac\fR. Here is a partial \fBpam.conf\fR
file with entries for \fBsac\fR using the UNIX session management module.
.sp
.in +2
.nf
sac  session   required   pam_unix_session.so.1
.fi
.in -2

.sp
.LP
If there are no entries for the \fBsac\fR service, then the entries for the
"other" service will be used.
.SH OPTIONS
.sp
.ne 2
.na
\fB\fB-t\fR \fIsanity_interval\fR\fR
.ad
.RS 22n
Sets the frequency (\fIsanity_interval\fR) with which \fBsac\fR polls the port
monitors on the system.
.RE

.SH FILES
.RS +4
.TP
.ie t \(bu
.el o
\fB/etc/saf/_sactab\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/etc/saf/_sysconfig\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/var/adm/utmpx\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/var/saf/_log\fR
.RE
.SH SEE ALSO
.sp
.LP
\fBpmadm\fR(1M), \fBsacadm\fR(1M), \fBfork\fR(2) \fBpam\fR(3PAM),
\fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5),
\fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5),
\fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5),
\fBpam_unix_session\fR(5)
.SH NOTES
.sp
.LP
The \fBpam_unix\fR(5) module is no longer supported. Similar functionality is
provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5),
\fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5),
\fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and
\fBpam_unix_session\fR(5).
.sp
.LP
The service access controller service is managed by the service management
facility, \fBsmf\fR(5), under the service identifier:
.sp
.in +2
.nf
svc:/system/sac:default
.fi
.in -2
.sp

.sp
.LP
Administrative actions on this service, such as enabling, disabling, or
requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
status can be queried using the \fBsvcs\fR(1) command.