lib/libutil/login_class.3

   1 .\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, is permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice immediately at the beginning of the file, without modification,
   9 .\"    this list of conditions, and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
  14 .\"    is permitted provided this notation is included.
  15 .\" 4. Absolutely no warranty of function or purpose is made by the author
  16 .\"    David Nugent.
  17 .\" 5. Modifications may be freely made to this file providing the above
  18 .\"    conditions are met.
  19 .\"
  20 .\" $FreeBSD$
  21 .\"
  22 .Dd December 28, 1996
  23 .Os
  24 .Dt LOGIN_CLASS 3
  25 .Sh NAME
  26 .Nm setclasscontext ,
  27 .Nm setclassenvironment ,
  28 .Nm setclassresources ,
  29 .Nm setusercontext
  30 .Nd "functions for using the login class capabilities database"
  31 .Sh LIBRARY
  32 .Lb libutil
  33 .Sh SYNOPSIS
  34 .In sys/types.h
  35 .In login_cap.h
  36 .Ft int
  37 .Fn setclasscontext "const char *classname" "unsigned int flags"
  38 .Ft int
  39 .Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "unsigned int flags"
  40 .Ft void
  41 .Fn setclassresources "login_cap_t *lc"
  42 .Ft void
  43 .Fn setclassenvironment "login_cap_t *lc" "const struct passwd *pwd" "int paths"
  44 .Sh DESCRIPTION
  45 These functions provide a higher level interface to the login class
  46 database than those documented in
  47 .Xr login_cap 3 .
  48 These functions are used to set resource limits, environment and
  49 accounting settings for users on logging into the system and when
  50 selecting an appropriate set of environment and resource settings
  51 for system daemons based on login classes.
  52 These functions may only be called if the current process is
  53 running with root privileges.
  54 If the LOGIN_SETLOGIN flag is used this function calls
  55 .Xr setlogin 2 ,
  56 and due care must be taken as detailed in the manpage for that
  57 function and this affects all processes running in the same session
  58 and not just the current process.
  59 .Pp
  60 The
  61 .Fn setclasscontext
  62 function sets various class context values (resource limits, umask and
  63 process priorities) based on values for a specific named class.
  64 .Pp
  65 The
  66 .Fn setusercontext
  67 function sets class context values based on a given login_cap_t
  68 object and a specific passwd record (if login_cap_t is NULL),
  69 the current session's login, and the current process
  70 user and group ownership.
  71 Each of these actions is selectable via bit-flags passed
  72 in the
  73 .Ar flags
  74 parameter, which is comprised of one or more of the following:
  75 .Bl -tag -width LOGIN_SETRESOURCES
  76 .It LOGIN_SETLOGIN
  77 Set the login associated with the current session to the user
  78 specified in the passwd structure using
  79 .Xr setlogin 2 .
  80 The
  81 .Ar pwd
  82 parameter must not be NULL if this option is used.
  83 .It LOGIN_SETUSER
  84 Set ownership of the current process to the uid specified in the
  85 .Ar uid
  86 parameter using
  87 .Xr setuid 2 .
  88 .It LOGIN_SETGROUP
  89 Set group ownership of the current process to the group id
  90 specified in the passwd structure using
  91 .Xr setgid 2 ,
  92 and calls
  93 .Xr initgroups 3
  94 to set up the group access list for the current process.
  95 The
  96 .Ar pwd
  97 parameter must not be NULL if this option is used.
  98 .It LOGIN_SETRESOURCES
  99 Set resource limits for the current process based on values
 100 specified in the system login class database.
 101 Class capability tags used, with and without -cur (soft limit)
 102 or -max (hard limit) suffixes and the corresponding resource
 103 setting:
 104 .Bd -literal
 105 cputime       RLIMIT_CPU
 106 filesize      RLIMIT_FSIZE
 107 datasize      RLIMIT_DATA
 108 stacksize     RLIMIT_STACK
 109 coredumpsize  RLIMIT_CORE
 110 memoryuse     RLIMIT_RSS
 111 memorylocked  RLIMIT_MEMLOCK
 112 maxproc       RLIMIT_NPROC
 113 openfiles     RLIMIT_NOFILE
 114 sbsize        RLIMIT_SBSIZE
 115 vmemoryuse    RLIMIT_VMEM
 116 .Ed
 117 .It LOGIN_SETPRIORITY
 118 Set the scheduling priority for the current process based on the
 119 value specified in the system login class database.
 120 Class capability tags used:
 121 .Bd -literal
 122 priority
 123 .Ed
 124 .It LOGIN_SETUMASK
 125 Set the umask for the current process to a value in the user or
 126 system login class database.
 127 Class capability tags used:
 128 .Bd -literal
 129 umask
 130 .Ed
 131 .It LOGIN_SETPATH
 132 Set the "path" and "manpath" environment variables based on values
 133 in the user or system login class database.
 134 Class capability tags used with the corresponding environment
 135 variables set:
 136 .Bd -literal
 137 path          PATH
 138 manpath       MANPATH
 139 .Ed
 140 .It LOGIN_SETENV
 141 Set various environment variables based on values in the user or
 142 system login class database.
 143 Class capability tags used with the corresponding environment
 144 variables set:
 145 .Bd -literal
 146 lang          LANG
 147 charset       MM_CHARSET
 148 timezone      TZ
 149 term          TERM
 150 .Ed
 151 .Pp
 152 Additional environment variables may be set using the list type
 153 capability "setenv=var1 val1,var2 val2..,varN valN".
 154 .It LOGIN_SETMAC
 155 Set the MAC label for the current process to the label specified
 156 in system login class database.
 157 .Pp
 158 .It LOGIN_SETALL
 159 Enables all of the above settings.
 160 .El
 161 .Pp
 162 Note that when setting environment variables and a valid passwd
 163 pointer is provided in the
 164 .Ar pwd
 165 parameter, the characters
 166 .Ql \&~
 167 and
 168 .Ql \&$
 169 are substituted for the user's home directory and login name
 170 respectively.
 171 .Pp
 172 The
 173 .Fn setclassresources
 174 and
 175 .Fn setclassenvironment
 176 functions are subsets of the setcontext functions above, but may
 177 be useful in isolation.
 178 .Sh RETURN VALUES
 179 The
 180 .Fn setclasscontext
 181 and
 182 .Fn setusercontext
 183 functions return -1 if an error occurred, or 0 on success.
 184 If an error occurs when attempting to set the user, login, group
 185 or resources, a message is reported to
 186 .Xr syslog 3 ,
 187 with LOG_ERR priority and directed to the currently active facility.
 188 .Sh SEE ALSO
 189 .Xr setgid 2 ,
 190 .Xr setlogin 2 ,
 191 .Xr setuid 2 ,
 192 .Xr getcap 3 ,
 193 .Xr initgroups 3 ,
 194 .Xr login_cap 3 ,
 195 .Xr mac_set_proc 3 ,
 196 .Xr login.conf 5 ,
 197 .Xr termcap 5