# Copyright © 1995 Peter Tobias <tobias@et-inf.fho-emden.de>
# Copyright © 2012 Serafeim Zanikolas <sez@debian.org>
# Copyright © 2018-2021 Guillem Jover <guillem@debian.org>
#
# 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, or
# (at your option) any later version.
#
# 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, see <https://www.gnu.org/licenses/>.

=encoding utf8

=head1 NAME

update-inetd - create, remove, enable or disable entry /etc/inetd.conf

=head1 SYNOPSIS

B<update-inetd> [I<option>...] I<command> I<argument>

=head1 DESCRIPTION

B<update-inetd> can be used to add, remove, enable or disable entries in
the F</etc/inetd.conf> file (you can specify a different file by using the
B<--file> option). After the F</etc/inetd.conf> file has been changed,
B<update-inetd> will send a B<SIGHUP> signal to the inetd process to make
sure that inetd will use the new F</etc/inetd.conf> file. For Perl scripts
you can also use the Perl module B<DebianNet>. See L<DebianNet(3pm)> for
further information. B<update-inetd> can also be used to add entries that
are commented out by default. They will be treated like normal entries.
That also means that if you already have an entry that is commented out you
cannot add an entry for the same service without removing the old one first.

In accordance with the Debian Policy, B<update-inetd> treats entries that
are prefixed with a single 'B<#>' character as commented out by a user. This
means that for a user to disable a service using B<update-inetd>, and for the
service to remain disabled after upgrades, the user must run B<update-inetd>
with B<--comment-chars '#'> (see relevant option below). Conversely, package
maintainer scripts should not override the default comment chars (and when
they do, they must not use 'B<#>').

Also note that B<--enable> and B<--remove> will not be acted upon for service
entries that are commented out using anything but the value specified with
B<--comment-chars> (or the default value if none is specified).

=head1 COMMANDS

=over 4

=item B<--add> I<entry-line>

Add an entry to F</etc/inetd.conf>. A description of the I<entry-line> format
can be found in the L<inetd(8)> or L<inetd.conf(5)> manual pages (or just
look at F</etc/inetd.conf>). In order to prevent the shell from changing
your I<entry-line> definition you have to quote the I<entry-line> using
single or double quotes. You can use tabs (tab character or \t) and spaces
to separate the fields of the I<entry-line>. To add the I<entry-line> to a
specific section in the F</etc/inetd.conf> file please use the B<--group>
option.

If you are trying to add an entry which already exists, B<update-inetd>
will not add the entry. For uncommented entries it will do nothing and
for entries that are commented out by the comment-chars (see option
B<--comment-chars>) it will enable the existing entry. If you want to
completely replace an entry just remove the entry with the B<--remove>
command first.

=item B<--remove> I<entry-regex>

Remove an entry-line matching I<entry-regex> (e.g. "I<telnet>") from
F</etc/inetd.conf>. The I<entry-regex> will be anchored at the beginning
of the entry line.

=item B<--enable> I<service>[,...]

Enable I<service> (e.g. "I<ftp>") in F</etc/inetd.conf>. If you want to
enable more than one I<service> you can use a comma-separated list of
services (no whitespace characters allowed).

=item B<--disable> I<service>[,...]

Disable I<service> (e.g. "I<ftp>") in F</etc/inetd.conf>. If you want to
disable more than one I<service> you can use a comma-separated list of
services (no whitespace characters allowed).

=back

=head1 OPTIONS

=over 4

=item B<--group> I<groupname>

Specify that the new entry should be placed in group I<groupname>
(e.g. "I<MAIL>"). If the group does not exist the entry will be placed
at the end of the file. The default group is "B<OTHER>".

This option is only relevant with the B<--add> command.

=item B<--pattern> I<pattern>

This option can be used to select a service. You only need this option if
you have two (or more) services of the same name.

This option is not relevant with the B<--add> command.

=item B<--comment-chars> I<characters>

B<update-inetd> uses "B<#E<lt>offE<gt># >" as the default comment characters.
You can use this option to specify different comment characters. This is only
necessary if you have to deal with two (or more) services of the same name.
If you do use this option, it is your responsibility to eventually remove
the commented out entry.

=item B<--multi>

If you want to disable/remove more than one entry at a time you should use
this option. If you try to remove more than one entry at a time without
using this option the program will show a warning and prompt the user for
an explicit confirmation.

=item B<--file> I<filename>

Use I<filename> instead of F</etc/inetd.conf>.

=item B<--verbose>

Explain what is being done.

=item B<--debug>

Enables debugging mode.

=item B<--help>

Print a usage message on standard output and exit successfully.

=item B<--version>

Print version information on standard output and exit successfully.

=back

=head1 EXAMPLES

You have installed ssh (secure encrypting remote shell) and wish to
disable its unencrypted cousins:

  update-inetd --comment-chars '#' --disable login,shell,exec,telnet

Using a single 'B<#>' character as a comment-char prevents B<update-inetd>
to re-enable the services on package upgrades.

You think the clock on your computer is often inaccurate and wish to make
sure other computers cannot read it:

  update-inetd --comment-chars '#' --disable time,daytime

You get the clock fixed:

  update-inetd --enable time,daytime

You hear a rumor that inetd is easily crashed via a SYN attack against
the time and daytime services, you want to turn off only their TCP
versions, while leaving the analogous UDP services enabled:

  update-inetd --comment-chars '#' --pattern tcp --disable time,daytime

You just finished writing a POP3 server and want to install the
F</etc/inetd.conf> entry from the Makefile:

  update-inetd --group MAIL --add \
    'pop-3\t\tstream\ttcp\tnowait\troot\t/usr/sbin/tcpd\t/usr/sbin/in.pop3d'

=head1 FILES

F</etc/inetd.conf>
F</run/inetd.pid>

=head1 SEE ALSO

L<inetd(8)>,
L<DebianNet(3pm)>.

=cut
