<?xml version="1.0" encoding="UTF-8"?>
<!-- **************************************************************************
.... For copyright and licensing terms, see the file named COPYING.
.... **************************************************************************
.-->
<?xml-stylesheet href="docbook-xml.css" type="text/css"?>

<refentry id="ttylogin-starter">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>ttylogin-starter</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">user commands</refmiscinfo>
<refmiscinfo class="source">nosh</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv>
<refname>ttylogin-starter</refname>
<refpurpose>demand-start ttylogin@.service services on active kernel virtual terminals</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>ttylogin-starter</command>
<arg choice='opt'>--verbose</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>
<command>ttylogin-starter</command> automatically runs <citerefentry><refentrytitle>system-control</refentrytitle><manvolnum>1</manvolnum></citerefentry> to start a <code>ttylogin@.service</code> service on kernel virtual terminals as they are switched-to.
It does not apply to user-space virtual terminals or to real terminals.
</para>

<para>
Conventionally, in the absence of <command>ttylogin-starter</command>, TUI login services for all terminals are enabled and disabled in the usual way; and started as a consequence of being wanted by the <command>multi-user</command> target.
The external configuration file import subsystem will <command>preset</command> all relevant <code>ttylogin@.service</code> services, using the <citerefentry><refentrytitle>ttys</refentrytitle><manvolnum>5</manvolnum></citerefentry> database (and any presets) to determine whether a TUI login service is enabled or disabled, as explained in <citerefentry><refentrytitle>system-control</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>

<refsection><title>BSDs</title>

<para>
On the BSDs, the conventional mechanism applies to all terminals, virtual and real.
<command>ttylogin-starter</command> does nothing on the BSDs, except pause forever.
It exists for script compatibility only.
</para>

</refsection>
<refsection><title>Linux</title>

<para>
On Linux, one can alternatively arrange, for just <emphasis>kernel virtual</emphasis> terminals specifically, for TUI login services to be started on-demand, as the terminals are switched to and become the "active" kernel virtual terminal, rather than have them always running.
This is done by disabling all kernel virtual terminals and letting <command>ttylogin-starter</command> start them on-demand, which it does with the <command>system-control</command> <arg choice="plain">start</arg> command, ignoring the disabled state of the service.
</para>

<para>
It does this by looping forever, monitoring the state of the <code>/sys/class/tty/tty0/active</code> file with <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
This file reports the currently active kernel virtual terminal name.
Each time that <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> reports a change in the currently active virtual terminal, <command>ttylogin-starter</command> starts the TUI login service for that terminal.
</para>

<para>
If the services do not exist, it makes no attempt to create them.
</para>

</refsection>

</refsection>

<refsection><title>Compatibility</title>

<para>
Currently, no provision is made for excluding kernel virtual terminals that are used by X servers or by <citerefentry><refentrytitle>console-fb-realizer</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
<command>ttylogin-starter</command> should not be used in conjunction with either of those, and instead the normal service enable/disable mechanism should be employed.
</para>

</refsection>

<refsection><title>See also</title>

<variablelist>
<varlistentry>
<term><citerefentry><refentrytitle>linux-vt</refentrytitle><manvolnum>4</manvolnum></citerefentry></term>
<listitem>
<para>
Kernel virtual terminal switching on Linux
</para>
</listitem>
</varlistentry>
</variablelist>

</refsection>

<refsection><title>Author</title>
<para><author><personname><firstname>Jonathan</firstname> <surname>de Boyne Pollard</surname></personname></author></para>
</refsection>

</refentry>
