nut/docs/man/upsdrvctl.8

'\" t
.\"     Title: upsdrvctl
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/26/2022
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.0
.\"  Language: English
.\"
.TH "UPSDRVCTL" "8" "04/26/2022" "Network UPS Tools 2\&.8\&.0" "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"
upsdrvctl \- UPS driver controller
.SH "SYNOPSIS"
.sp
\fBupsdrvctl\fR \-h
.sp
\fBupsdrvctl\fR [\fIOPTIONS\fR] {start | stop | shutdown} [\fIups\fR]
.SH "DESCRIPTION"
.sp
\fBupsdrvctl\fR provides a uniform interface for controlling your UPS drivers\&. You should use upsdrvctl instead of direct calls to the drivers whenever possible\&.
.sp
When used properly, upsdrvctl lets you maintain identical startup scripts across multiple systems with different UPS configurations\&.
.sp
Note: For operating systems with service management frameworks, such as Solaris SMF or Linux systemd, the \fBupsdrvsvcctl\fR may be a better choice\&.
.SH "OPTIONS"
.PP
\fB\-h\fR
.RS 4
Display the help text\&.
.RE
.PP
\fB\-r\fR \fIdirectory\fR
.RS 4
If starting a driver, this value will direct it to
\fBchroot\fR(2) into
\fIdirectory\fR\&. This can be useful when securing systems\&.
.RE
.sp
This may be set in the ups\&.conf with "chroot" in the global section\&.
.PP
\fB\-t\fR
.RS 4
Enable testing mode\&. This also enables debug mode\&. Testing mode makes upsdrvctl display the actions it would execute without actually doing them\&. Use this to test out your configuration without actually doing anything to your UPS drivers\&. This may be helpful when defining the
\fIsdorder\fR
directive in your
\fBups.conf\fR(5)\&.
.RE
.PP
\fB\-u\fR \fIusername\fR
.RS 4
If starting a driver, this value will direct it to
\fBsetuid\fR(2) to the user id associated with
\fIusername\fR\&.
.RE
.sp
If the driver is started as root without specifying this value, it will use the username that was compiled into the binary\&. This defaults to "nobody", and is far from ideal\&.
.sp
This may be set in ups\&.conf with "user" in the global section\&.
.PP
\fB\-D\fR
.RS 4
Raise the debug level\&. Use this multiple times for additional details\&.
.RE
.PP
\fB\-d\fR
.RS 4
Pass the selected debug level from
upsdrvctl
to launched drivers\&.
.RE
.SH "COMMANDS"
.sp
upsdrvctl supports three commands \- start, stop and shutdown\&. They take an optional argument which is a UPS name from \fBups.conf\fR(5)\&. Without that argument, they operate on every UPS that is currently configured\&.
.PP
\fBstart\fR
.RS 4
Start the UPS driver(s)\&. In case of failure, further attempts may be executed by using the
\fImaxretry\fR
and
\fIretrydelay\fR
options \- see
\fBups.conf\fR(5)\&.
.RE
.PP
\fBstop\fR
.RS 4
Stop the UPS driver(s)\&.
.RE
.PP
\fBshutdown\fR
.RS 4
Command the UPS driver(s) to run their shutdown sequence\&. Drivers are stopped according to their sdorder value \- see
\fBups.conf\fR(5)\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
.sp
this will probably power off your computers, so don\(cqt play around with this option\&. Only use it when your systems are prepared to lose power\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
refer to \fBups.conf\fR(5) for using the \fBnowait\fR parameter\&.
.sp .5v
.RE
.SH "ENVIRONMENT VARIABLES"
.sp
\fBNUT_CONFPATH\fR is the path name of the directory that contains upsd\&.conf and other configuration files\&. If this variable is not set, \fBupsdrvctl\fR the driver use a built\-in default, which is often /usr/local/ups/etc\&.
.SH "DIAGNOSTICS"
.sp
upsdrvctl will return a nonzero exit code if it encounters an error while performing the desired operation\&. This will also happen if a driver takes longer than the \fImaxstartdelay\fR period to enter the background\&.
.SH "SEE ALSO"
.sp
\fBupsdrvsvcctl\fR(8), \fBnutupsdrv\fR(8), \fBupsd\fR(8), \fBups.conf\fR(5)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/