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: src/lib/libutil/login_class.3,v 1.9.2.4 2003/04/29 14:40:07 trhodes Exp $
  21 .\"
  22 .Dd December 28, 1996
  23 .Dt LOGIN_CLASS 3
  24 .Os
  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 int
  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 .Fn setclasscontext
  61 sets various class context values (resource limits, umask and
  62 process priorities) based on values for a specific named class.
  63 .Pp
  64 The function
  65 .Fn setusercontext
  66 sets class context values based on a given login_cap_t
  67 object, a specific passwd record (if login_cap_t is NULL),
  68 sets the current session's login and the current process
  69 user and group ownership.
  70 Each of these functions is selectable via bit-flags passed
  71 in the
  72 .Ar flags
  73 parameter, which is comprised of one or more of the following:
  74 .Bl -tag -width LOGIN_SETRESOURCES
  75 .It LOGIN_SETLOGIN
  76 Set the login associated with the current session to the user
  77 specified in the passwd structure.
  78 .Xr setlogin 2 .
  79 The
  80 .Ar pwd
  81 parameter must not be NULL if this option is used.
  82 .It LOGIN_SETUSER
  83 Set ownership of the current process to the uid specified in the
  84 .Ar uid
  85 parameter using
  86 .Xr setuid 2 .
  87 .It LOGIN_SETGROUP
  88 Set group ownership of the current process to the group id
  89 specified in the passwd structure using
  90 .Xr setgid 2 ,
  91 and calls
  92 .Xr initgroups 3
  93 to set up the group access list for the current process.
  94 The
  95 .Ar pwd
  96 parameter must not be NULL if this option is used.
  97 .It LOGIN_SETRESOURCES
  98 Set resource limits for the current process based on values
  99 specified in the system login class database.
 100 Class capability tags used, with and without -cur (soft limit)
 101 or -max (hard limit) suffixes and the corresponding resource
 102 setting:
 103 .Bd -literal
 104 cputime       RLIMIT_CPU
 105 filesize      RLIMIT_FSIZE
 106 datasize      RLIMIT_DATA
 107 stacksize     RLIMIT_STACK
 108 coredumpsize  RLIMIT_CORE
 109 memoryuse     RLIMIT_RSS
 110 memorylocked  RLIMIT_MEMLOCK
 111 maxproc       RLIMIT_NPROC
 112 openfiles     RLIMIT_NOFILE
 113 sbsize        RLIMIT_SBSIZE
 114 vmemoryuse    RLIMIT_VMEM
 115 .Ed
 116 .It LOGIN_SETPRIORITY
 117 Set the scheduling priority for the current process based on the
 118 value specified in the system login class database.
 119 Class capability tags used:
 120 .Bd -literal
 121 priority
 122 .Ed
 123 .It LOGIN_SETUMASK
 124 Set the umask for the current process to a value in the user or
 125 system login class database.
 126 Class capability tags used:
 127 .Bd -literal
 128 umask
 129 .Ed
 130 .It LOGIN_SETPATH
 131 Set the "path" and "manpath" environment variables based on values
 132 in the user or system login class database.
 133 Class capability tags used with the corresponding environment
 134 variables set:
 135 .Bd -literal
 136 path          PATH
 137 manpath       MANPATH
 138 .Ed
 139 .It LOGIN_SETENV
 140 Set various environment variables based on values in the user or
 141 system login class database.
 142 Class capability tags used with the corresponding environment
 143 variables set:
 144 .Bd -literal
 145 lang          LANG
 146 charset       MM_CHARSET
 147 timezone      TZ
 148 term          TERM
 149 .Ed
 150 .Pp
 151 Additional environment variables may be set using the list type
 152 capability "setenv=var1 val1,var2 val2..,varN valN".
 153 .It LOGIN_SETALL
 154 Enables all of the above settings.
 155 .El
 156 .Pp
 157 Note that when setting environment variables and a valid passwd
 158 pointer is provided in the
 159 .Ar pwd
 160 parameter, the characters
 161 .Ql \&~
 162 and
 163 .Ql \&$
 164 are substituted for the user's home directory and login name
 165 respectively.
 166 .Pp
 167 The
 168 .Fn setclassresources
 169 and
 170 .Fn setclassenvironment
 171 functions are subsets of the setcontext functions above, but may
 172 be useful in isolation.
 173 .Sh RETURN VALUES
 174 .Fn setclassenvironment
 175 ,
 176 .Fn setclasscontext
 177 and
 178 .Fn setusercontext
 179 return -1 if an error occurred, or 0 on success.
 180 If an error occurs when attempting to set the user, login, group
 181 or resources, a message is reported to
 182 .Xr syslog 3 ,
 183 with LOG_ERR priority and directed to the currently active facility.
 184 .Sh ERRORS
 185 .Bl -tag -width Er
 186 .It Bq Er ENOMEM
 187 The function
 188 .Fn setclassenvironment
 189 failed because it were unable to allocate memory for the environment.
 190 .El
 191 .Sh SEE ALSO
 192 .Xr setgid 2 ,
 193 .Xr setlogin 2 ,
 194 .Xr setuid 2 ,
 195 .Xr getcap 3 ,
 196 .Xr initgroups 3 ,
 197 .Xr login_cap 3 ,
 198 .Xr login.conf 5 ,
 199 .Xr termcap 5