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 .\" $DragonFly: src/lib/libutil/login_class.3,v 1.4 2006/06/17 03:15:18 reed Exp $
  22 .\"
  23 .Dd December 28, 1996
  24 .Os
  25 .Dt LOGIN_CLASS 3
  26 .Sh NAME
  27 .Nm setclasscontext ,
  28 .Nm setclassenvironment ,
  29 .Nm setclassresources ,
  30 .Nm setusercontext
  31 .Nd "functions for using the login class capabilities database"
  32 .Sh LIBRARY
  33 .Lb libutil
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In login_cap.h
  37 .Ft int
  38 .Fn setclasscontext "const char *classname" "unsigned int flags"
  39 .Ft int
  40 .Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "unsigned int flags"
  41 .Ft void
  42 .Fn setclassresources "login_cap_t *lc"
  43 .Ft int
  44 .Fn setclassenvironment "login_cap_t *lc" "const struct passwd *pwd" "int paths"
  45 .Sh DESCRIPTION
  46 These functions provide a higher level interface to the login class
  47 database than those documented in
  48 .Xr login_cap 3 .
  49 These functions are used to set resource limits, environment and
  50 accounting settings for users on logging into the system and when
  51 selecting an appropriate set of environment and resource settings
  52 for system daemons based on login classes.
  53 These functions may only be called if the current process is
  54 running with root privileges.
  55 If the LOGIN_SETLOGIN flag is used this function calls
  56 .Xr setlogin 2 ,
  57 and due care must be taken as detailed in the manpage for that
  58 function and this affects all processes running in the same session
  59 and not just the current process.
  60 .Pp
  61 .Fn setclasscontext
  62 sets various class context values (resource limits, umask and
  63 process priorities) based on values for a specific named class.
  64 .Pp
  65 The function
  66 .Fn setusercontext
  67 sets class context values based on a given login_cap_t
  68 object, a specific passwd record (if login_cap_t is NULL),
  69 sets the current session's login and the current process
  70 user and group ownership.
  71 Each of these functions 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.
  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_SETALL
 155 Enables all of the above settings.
 156 .El
 157 .Pp
 158 Note that when setting environment variables and a valid passwd
 159 pointer is provided in the
 160 .Ar pwd
 161 parameter, the characters
 162 .Ql \&~
 163 and
 164 .Ql \&$
 165 are substituted for the user's home directory and login name
 166 respectively.
 167 .Pp
 168 The
 169 .Fn setclassresources
 170 and
 171 .Fn setclassenvironment
 172 functions are subsets of the setcontext functions above, but may
 173 be useful in isolation.
 174 .Sh RETURN VALUES
 175 .Fn setclassenvironment
 176 ,
 177 .Fn setclasscontext
 178 and
 179 .Fn setusercontext
 180 return -1 if an error occurred, or 0 on success.
 181 If an error occurs when attempting to set the user, login, group
 182 or resources, a message is reported to
 183 .Xr syslog 3 ,
 184 with LOG_ERR priority and directed to the currently active facility.
 185 .Sh ERRORS
 186 .Bl -tag -width Er
 187 .It Bq Er ENOMEM
 188 The function
 189 .Fn setclassenvironment
 190 failed because it were unable to allocate memory for the environment.
 191 .El
 192 .Sh SEE ALSO
 193 .Xr setgid 2 ,
 194 .Xr setlogin 2 ,
 195 .Xr setuid 2 ,
 196 .Xr getcap 3 ,
 197 .Xr initgroups 3 ,
 198 .Xr login_cap 3 ,
 199 .Xr login.conf 5 ,
 200 .Xr termcap 5