share/man/man8/sac.8

   1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved
   4 .\" 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.
   5 .\"  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
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH SAC 8 "Apr 21, 2009"
   8 .SH NAME
   9 sac \- service access controller
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBsac\fR \fB-t\fR \fIsanity_interval\fR
  14 .fi
  15
  16 .LP
  17 .nf
  18 \fB/usr/lib/saf/sac\fR
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The Service Access Controller (SAC) is the overseer of the server machine. It
  25 is started when the server machine enters multiuser mode. The \fBSAC\fR
  26 performs several important functions as explained below.
  27 .SS "Customizing the SAC Environment"
  28 .sp
  29 .LP
  30 When \fBsac\fR is invoked, it first looks for the per-system configuration
  31 script \fB/etc/saf/_sysconfig\fR. \fBsac\fR interprets \fB_sysconfig\fR to
  32 customize its own environment. The modifications made to the \fBSAC\fR
  33 environment by \fB_sysconfig\fR are inherited by all the children of the
  34 \fBSAC.\fR This inherited environment may be modified by the children.
  35 .SS "Starting Port Monitors"
  36 .sp
  37 .LP
  38 After it has interpreted the \fB_sysconfig\fR file, the \fBsac\fR reads its
  39 administrative file \fB/etc/saf/_sactab\fR. \fB_sactab\fR specifies which port
  40 monitors are to be started. For each port monitor to be started, \fBsac\fR
  41 forks a child (see \fBfork\fR(2)) and creates a \fButmpx\fR entry with the
  42 \fBtype\fR field set to \fBLOGIN_PROCESS\fR. Each child then interprets its
  43 per-port monitor configuration script \fB/etc/saf/\fR\fIpmtag\fR\fB/_config\fR
  44 , if the file exists. These modifications to the environment  affect the port
  45 monitor and will be inherited by all its children. Finally, the child process
  46 \fBexec\fRs the port monitor, using the command found in the \fB_sactab\fR
  47 entry.  (See \fBsacadm\fR; this is the command given with the \fB-c\fR option
  48 when the port monitor is added to the system.)
  49 .SS "Polling Port Monitors to Detect Failure"
  50 .sp
  51 .LP
  52 The \fB-t\fR option sets the frequency with which \fBsac\fR polls the port
  53 monitors on the system. This time may also be thought of as half of the maximum
  54 latency required to detect that a port monitor has failed and that recovery
  55 action is necessary.
  56 .SS "Administrative functions"
  57 .sp
  58 .LP
  59 The Service Access Controller represents the administrative point of control
  60 for port monitors. Its administrative tasks are explained below.
  61 .sp
  62 .LP
  63 When queried (\fBsacadm\fR with either \fB-l\fR or \fB-L\fR), the Service
  64 Access Controller returns the status  of the port monitors specified, which
  65 \fBsacadm\fR prints on the standard output. A port monitor may be in one of six
  66 states:
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBENABLED\fR\fR
  71 .ad
  72 .RS 14n
  73 The port monitor is currently running and is accepting connections. See
  74 \fBsacadm\fR(8) with the \fB-e\fR option.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBDISABLED\fR\fR
  81 .ad
  82 .RS 14n
  83 The port monitor is currently running and is not accepting connections. See
  84 \fBsacadm\fR with the \fB-d\fR option, and see \fBNOTRUNNING\fR, below.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBSTARTING\fR\fR
  91 .ad
  92 .RS 14n
  93 The port monitor is in the process of starting up. \fBSTARTING\fR is an
  94 intermediate state  on the way to \fBENABLED\fR or \fBDISABLED\fR.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBFAILED\fR\fR
 101 .ad
 102 .RS 14n
 103 The port monitor was unable to start and remain running.
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBSTOPPING\fR\fR
 110 .ad
 111 .RS 14n
 112 The port monitor has been manually terminated but has not completed its
 113 shutdown procedure. \fBSTOPPING\fR is an intermediate state on the way to
 114 \fBNOTRUNNING\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBNOTRUNNING\fR\fR
 121 .ad
 122 .RS 14n
 123 The port monitor is not currently running. (See \fBsacadm\fR with \fB-k\fR.)
 124 This is the normal "not running" state. When a port monitor is killed, all
 125 ports it was monitoring are inaccessible.  It is not possible for an external
 126 user to tell whether a port is not being monitored or the system is down. If
 127 the port monitor is not killed but is in the \fBDISABLED\fR state, it may be
 128 possible (depending on the port monitor being used) to write a message on the
 129 inaccessible port telling the user who is trying to access the port that it is
 130 disabled. This is the advantage of having a \fBDISABLED\fR state as well as the
 131 \fBNOTRUNNING\fR state.
 132 .RE
 133
 134 .sp
 135 .LP
 136 When a port monitor terminates, the \fBSAC\fR removes the \fButmpx\fR entry for
 137 that port monitor.
 138 .sp
 139 .LP
 140 The \fBSAC\fR receives all requests to enable, disable, start, or stop port
 141 monitors and  takes the appropriate action.
 142 .sp
 143 .LP
 144 The \fBSAC\fR is responsible for restarting port monitors that terminate.
 145 Whether or not the \fBSAC\fR will restart a given port monitor depends on two
 146 things:
 147 .RS +4
 148 .TP
 149 .ie t \(bu
 150 .el o
 151 The restart count specified for the port monitor when the port monitor was
 152 added by \fBsacadm\fR; this information is included in
 153 \fB/etc/saf/\fR\fIpmtag\fR\fB/_sactab.\fR
 154 .RE
 155 .RS +4
 156 .TP
 157 .ie t \(bu
 158 .el o
 159 The number of times the port monitor has already been restarted.
 160 .RE
 161 .SH SECURITY
 162 .sp
 163 .LP
 164 \fBsac\fR uses \fBpam\fR(3PAM) for session management.  The \fBPAM\fR
 165 configuration policy, listed through \fB/etc/pam.conf\fR, specifies the session
 166 management module to be used for \fBsac\fR. Here is a partial \fBpam.conf\fR
 167 file with entries for \fBsac\fR using the UNIX session management module.
 168 .sp
 169 .in +2
 170 .nf
 171 sac  session   required   pam_unix_session.so.1
 172 .fi
 173 .in -2
 174
 175 .sp
 176 .LP
 177 If there are no entries for the \fBsac\fR service, then the entries for the
 178 "other" service will be used.
 179 .SH OPTIONS
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fB-t\fR \fIsanity_interval\fR\fR
 184 .ad
 185 .RS 22n
 186 Sets the frequency (\fIsanity_interval\fR) with which \fBsac\fR polls the port
 187 monitors on the system.
 188 .RE
 189
 190 .SH FILES
 191 .RS +4
 192 .TP
 193 .ie t \(bu
 194 .el o
 195 \fB/etc/saf/_sactab\fR
 196 .RE
 197 .RS +4
 198 .TP
 199 .ie t \(bu
 200 .el o
 201 \fB/etc/saf/_sysconfig\fR
 202 .RE
 203 .RS +4
 204 .TP
 205 .ie t \(bu
 206 .el o
 207 \fB/var/log/utmpx\fR
 208 .RE
 209 .RS +4
 210 .TP
 211 .ie t \(bu
 212 .el o
 213 \fB/var/saf/_log\fR
 214 .RE
 215 .SH SEE ALSO
 216 .sp
 217 .LP
 218 \fBpmadm\fR(8), \fBsacadm\fR(8), \fBfork\fR(2) \fBpam\fR(3PAM),
 219 \fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5),
 220 \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5),
 221 \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5),
 222 \fBpam_unix_session\fR(5)
 223 .SH NOTES
 224 .sp
 225 .LP
 226 The \fBpam_unix\fR(5) module is no longer supported. Similar functionality is
 227 provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5),
 228 \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5),
 229 \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and
 230 \fBpam_unix_session\fR(5).
 231 .sp
 232 .LP
 233 The service access controller service is managed by the service management
 234 facility, \fBsmf\fR(5), under the service identifier:
 235 .sp
 236 .in +2
 237 .nf
 238 svc:/system/sac:default
 239 .fi
 240 .in -2
 241 .sp
 242
 243 .sp
 244 .LP
 245 Administrative actions on this service, such as enabling, disabling, or
 246 requesting restart, can be performed using \fBsvcadm\fR(8). The service's
 247 status can be queried using the \fBsvcs\fR(1) command.