'\" t
.\"     Title: upsd.users
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/29/2025
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.3
.\"  Language: English
.\"
.TH "UPSD\&.USERS" "5" "05/29/2025" "Network UPS Tools 2\&.8\&.3" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
upsd.users \- Administrative user definitions for NUT upsd data server
.SH "DESCRIPTION"
.sp
Administrative commands such as setting variables and the instant commands are powerful, and access to them needs to be restricted\&. This file defines who may access them, and what is available\&.
.SH "IMPORTANT NOTES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Balance the run\-time user permissions to access the file (and perhaps the directory it is in) for only
upsd
to be able to read it; write access is not needed\&. It is common to use
chown root:nut
and
chmod 640
to set up acceptable file permissions\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Packages (and build recipes) typically prepare one set of user and group accounts for NUT\&. Custom builds with minimal configuration might even use
nobody:nogroup
or similar, which is inherently insecure\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
On systems with extra security concerns, NUT drivers and data server should run as separate user accounts which would be members of one same group for shared access to local Unix socket files and the directory they are in, but different groups for configuration file access\&. This would need some daemons to use customized
user,
group,
RUN_AS_USER
and/or
RUN_AS_GROUP
settings to override the single built\-in value\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Note that the monitoring, logging, etc\&. clients are networked\-only\&. They do not need access to these files and directories, and can run as an independent user and group altogether\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Keep in mind the security of also any backup copies of this file, e\&.g\&. the archive files it might end up in\&.
.RE
.RE
.SH "SECTIONS"
.sp
Each user gets its own section\&. The fields in that section set the parameters associated with that user\(cqs privileges\&. The section begins with the name of the user in brackets, and continues until the next user name in brackets or EOF\&. These users are independent of /etc/passwd or other OS account databases\&.
.sp
Here are some examples to get you started:
.sp
.if n \{\
.RS 4
.\}
.nf
[admin]
        password = mypass
        actions = set
        actions = fsd
        instcmds = all
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[pfy]
        password = duh
        instcmds = test\&.panel\&.start
        instcmds = test\&.panel\&.stop
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[upswired]
        password = blah
        upsmon primary
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[observer]
        password = abcd
        upsmon secondary
.fi
.if n \{\
.RE
.\}
.SH "FIELDS"
.PP
\fBpassword\fR
.RS 4
Set the password for this user\&.
.RE
.PP
\fBactions\fR
.RS 4
Allow the user to do certain things with
upsd\&. To specify multiple actions, use multiple instances of the
\fBactions\fR
field\&. Valid actions are:
.PP
SET
.RS 4
change the value of certain variables in the UPS
.RE
.PP
FSD
.RS 4
set the forced shutdown flag in the UPS\&. This is equivalent to an "on battery + low battery" situation for the purposes of monitoring\&.
.RE
.sp
The list of actions is expected to grow in the future\&.
.RE
.PP
\fBinstcmds\fR
.RS 4
Let a user initiate specific instant commands\&. Use "ALL" to grant all commands automatically\&. To specify multiple commands, use multiple instances of the
\fBinstcmds\fR
field\&. For the full list of what your UPS supports, use
upscmd \-l\&.
.sp
The
cmdvartab
file supplied with the NUT distribution contains a list of most of the generally known command names\&.
.RE
.PP
\fBupsmon\fR
.RS 4
Add the necessary actions for an
upsmon
process, and can be viewed as a role of a particular client instance to work with this data server instance\&. This is either set to
\fIprimary\fR
(may request FSD) or
\fIsecondary\fR
(follows critical situations to shut down when needed)\&.
.sp
Do not attempt to assign actions to
upsmon
by hand, as you may miss something important\&. This method of designating a "upsmon user" was created so internal capabilities could be changed later on without breaking existing installations (potentially using actions that are not exposed for direct assignment)\&.
.RE
.SH "SEE ALSO"
.sp
\fBupsd\fR(8), \fBupsd.conf\fR(5)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: https://www\&.networkupstools\&.org/historic/v2\&.8\&.3/