153 lines
6.3 KiB
Groff
153 lines
6.3 KiB
Groff
'\" -*- coding: UTF-8 -*-
|
|
.\" Copyright (C) 2018 Jesse Smith
|
|
.\"
|
|
.\" This program is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the GNU General Public License as published by
|
|
.\" the Free Software Foundation; either version 2 of the License.
|
|
.\"
|
|
.\" This program is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License
|
|
.\" along with this program; if not, write to the Free Software
|
|
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
.\"
|
|
.TH INITCTL 5 "April 13, 2018" "sysvinit " "File Formats"
|
|
.SH NAME
|
|
initctl \- /run/initctl is a named pipe which passes commands to SysV init
|
|
.SH SYNOPSIS
|
|
/run/initctl
|
|
.SH DESCRIPTION
|
|
|
|
This document describes the communication pipe set up by SysV \fBinit\fR
|
|
at \fI/run/initctl\fR. This named pipe allows programs with the proper
|
|
permissions (typically programs run by root have read+write access to
|
|
the pipe) to send signals to the \fBinit\fR program (PID 1).
|
|
|
|
The \fBinit\fR manual page has, up until recently, simply stated
|
|
that people wishing to understand how to send messages to \fBinit\fR
|
|
should read the init program's source code, but that is not usually practical.
|
|
|
|
Messages sent to the pipe to talk to \fBinit\fR must have a special format.
|
|
This format is defined as a C structure and the technical break-down
|
|
is presented here:
|
|
|
|
/*
|
|
* Because of legacy interfaces, "runlevel" and "sleeptime"
|
|
* aren't in a separate struct in the union.
|
|
*
|
|
* The weird sizes are because init expects the whole
|
|
* struct to be 384 bytes.
|
|
*/
|
|
|
|
struct init_request {
|
|
int magic; /* Magic number */
|
|
int cmd; /* What kind of request */
|
|
int runlevel; /* Runlevel to change to */
|
|
int sleeptime; /* Time between TERM and KILL */
|
|
union {
|
|
struct init_request_bsd bsd;
|
|
char data[368];
|
|
} i;
|
|
};
|
|
|
|
|
|
Let's go through the init_request structure one line at a time. The
|
|
first variable, the "magic" number must be of the value 0x03091969.
|
|
The \fBinit\fR program then knows that only programs with root access which send
|
|
this magic number are authorized to communicate with init.
|
|
|
|
The \fIcmd\fR variable is a value in the range of 0-8 (currently). This \fIcmd\fR
|
|
variable tells init what we want it to do. Here are the possible options:
|
|
|
|
1 - Set the current runlevel, specified by the runlevel variable.
|
|
|
|
2 - The power will fail soon (probably low battery) prepare to shutdown.
|
|
|
|
3 - The power is failing, do shutdown immediately.
|
|
|
|
4 - The power is okay, cancel shutdown.
|
|
|
|
6 - Set an environment variable to a value to be specified in
|
|
the \fIdata\fR variable of this structure.
|
|
|
|
Other \fIcmd\fR options may be added to \fBinit\fR later. For example, command values
|
|
0, 5 and 7 are defined but currently not implemented.
|
|
|
|
The \fIrunlevel\fR variable will specify the runlevel to switch to (0-6).
|
|
|
|
The \fIsleeptime\fR variable is to be used when we want to tell \fBinit\fR to change
|
|
the time spent waiting between sending \fBSIGTERM\fR and \fBSIGKILL\fR during the
|
|
shutdown process. Changing this at run time is not yet implemented.
|
|
|
|
The \fIdata\fR variable (in the union) can be used to pass misc data which init
|
|
might need to process our request. For example, when setting environment
|
|
variables.
|
|
|
|
When setting an environment variable through \fBinit\fR's \fI/run/initctl\fR pipe,
|
|
the data variable should have the format \fIVARIABLE\fR=\fIVALUE\fR. The string
|
|
should be terminated with a NULL character.
|
|
|
|
.SH EXAMPLES
|
|
|
|
The following C code example shows how to send a set environment variable
|
|
request to the \fBinit\fR process using the \fI/run/initctl\fR pipe. This example
|
|
is simplified and skips the error checking. A more complete example can be
|
|
found in the shutdown.c program's \fBinit_setnv\fR() function.
|
|
|
|
.nf
|
|
struct init_request request; /* structure defined above */
|
|
int fd; /* file descriptor for pipe */
|
|
|
|
memset(&request, 0, sizeof(request)); /* initialize structure */
|
|
request.magic = 0x03091969; /* magic number required */
|
|
request.cmd = 6; /* 6 is to set a variable */
|
|
sprintf(request.data, "VARIABLE=VALUE"); /* set VAR to VALUE in init */
|
|
|
|
if ((fd = open(INIT_FIFO, O_WRONLY)) >= 0) /* open pipe for writing */
|
|
{
|
|
size_t s = sizeof(request); /* size of structure to write */
|
|
void *ptr = &request; /* temporary pointer */
|
|
write(fd, ptr, s); /* send structure to the pipe */
|
|
close(fd); /* close the pipe when done */
|
|
}
|
|
.fi
|
|
|
|
.sp
|
|
.SH NOTES
|
|
Usually the \fI/run/initctl\fR pipe would only be used by low-level programs to
|
|
request a power-related shutdown or change the runlevel, like \fBtelinit\fR
|
|
would do. Most of the time there is no need to talk to \fBinit\fR directly, but
|
|
this gives us an extendable approach so \fBinit\fR can be taught how to learn
|
|
more commands.
|
|
.PP
|
|
The commands passed through the \fI/run/initctl\fR pipe must be sent in a specific
|
|
binary format and be of a specific length. Larger data structures or ones
|
|
not using the proper format will be ignored. Typically, only root has the
|
|
ability to write to the initctl pipe for security reasons.
|
|
.PP
|
|
The \fI/run/initctl\fR pipe can be closed by sending init (PID 1) the \fBSIGUSR2\fR
|
|
signal. This closes the pipe and leaves it closed. This may be useful
|
|
for making sure \fBinit\fR is not keeping any files open. However, when the
|
|
pipe is closed, \fBinit\fR no longer receives signals, such as those sent by
|
|
\fBshutdown\fR(8) or \fBtelinit\fR(8). In other words if we close the pipe, \fBinit\fR cannot
|
|
change its runlevel directly. The pipe may be re-opened by sending \fBinit\fR (PID 1)
|
|
the \fBSIGUSR1\fR signal.
|
|
.PP
|
|
If the \fI/run/initctl\fR pipe is closed then it may still be possible to bring
|
|
down the system using the \fBshutdown\fR(8) command's \fB-n\fR flag, but this is not
|
|
always clean and not recommended.
|
|
|
|
.SH FILES
|
|
/run/initctl
|
|
/sbin/init
|
|
|
|
.SH AUTHOR
|
|
.MT jsmith@\:resonatingmedia\:.com
|
|
Jesse Smith
|
|
.ME
|
|
.SH "SEE ALSO"
|
|
.BR init (8)
|