<commit_before><?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="listen">
  <title>TCP Port and Address</title>

  <para>Cockpit's <code>cockpit-ws</code> component is configured by default to accept
    connections on port <code>9090</code>. This is the port that is documented for a
    "Web-based System Manager" to listen on. It is also relatively memorable.</para>

  <para>However there are many reasons you may wish to change the default port. For
    example other software may use port <code>9090</code> or you may wish to setup
    Cockpit to listen on <code>443</code> instead. It is also possible to have Cockpit
    only listen on one specific IP address.</para>

  <para>Note that it is only required to have Cockpit listening on a TCP port on
    the server that you access with your web browser. If you add multiple servers
    with host switcher, Cockpit will connect to those servers via
    <code>ssh</code>.</para>

  <para>The systems that Cockpit runs on are typically locked down with firewalls,
    SELinux, so changing the default port is not as easy as editing a configuration
    file.</para>

  <section id="listen-systemd">
    <title>Cockpit systemd Socket</title>

    <para>On servers with
      <ulink url="https://www.freedesktop.org/wiki/Software/systemd/"><code>systemd</code></ulink>
      Cockpit starts on demand via socket activation. To change its port and/or address
      you should place the following content in the
      <code>/etc/systemd/system/cockpit.socket.d/listen.conf</code> file. Create the file
      and directories in that path which not already exist. The <code>ListenStream</code>
      option specifies the desired address and TCP port.</para>

<programlisting>
[Socket]
ListenStream=
ListenStream=443
</programlisting>

<programlisting>
[Socket]
ListenStream=
ListenStream=192.168.1.1:443
FreeBind=yes
</programlisting>

    <para>NOTE: The first empty line is intentional. <code>systemd</code> allows multiple <code>Listen</code> directives to be declared in a single socket unit. To change the activation port instead of adding a second port, use a full override unit instead of a snippet.</para>

    <para>The <code>FreeBind</code> option is highly recommended when defining specific IP addresses. See the <ulink url="https://www.freedesktop.org/software/systemd/man/systemd.socket.html"><code>systemd.socket</code> manpage</ulink> for details.</para>

    <para>Cockpit can actually listen on multiple ports, also:</para>

<programlisting>
[Socket]
ListenStream=
ListenStream=443
ListenStream=7777
</programlisting>

    <para>As above, it's recommended to start with an override unit, otherwise it's possible one of your multiple listen addresses might conflict.</para>

    <para>In order for the changes to take effect, run the following commands:</para>

<programlisting>
$ sudo systemctl daemon-reload
$ sudo systemctl restart cockpit.socket
</programlisting><commit_msg>guide: Fix conflicting and redundant advice for ListenStream=<commit_after><?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="listen">
  <title>TCP Port and Address</title>

  <para>Cockpit's <code>cockpit-ws</code> component is configured by default to accept
    connections on port <code>9090</code>. This is the port that is documented for a
    "Web-based System Manager" to listen on. It is also relatively memorable.</para>

  <para>However there are many reasons you may wish to change the default port. For
    example other software may use port <code>9090</code> or you may wish to setup
    Cockpit to listen on <code>443</code> instead. It is also possible to have Cockpit
    only listen on one specific IP address.</para>

  <para>Note that it is only required to have Cockpit listening on a TCP port on
    the server that you access with your web browser. If you add multiple servers
    with host switcher, Cockpit will connect to those servers via
    <code>ssh</code>.</para>

  <para>The systems that Cockpit runs on are typically locked down with firewalls,
    SELinux, so changing the default port is not as easy as editing a configuration
    file.</para>

  <section id="listen-systemd">
    <title>Cockpit systemd Socket</title>

    <para>On servers with
      <ulink url="https://www.freedesktop.org/wiki/Software/systemd/"><code>systemd</code></ulink>
      Cockpit starts on demand via socket activation. To change its port and/or address
      you should place the following content in the
      <code>/etc/systemd/system/cockpit.socket.d/listen.conf</code> file. Create the file
      and directories in that path which not already exist. The <code>ListenStream</code>
      option specifies the desired address and TCP port.</para>

<programlisting>
[Socket]
ListenStream=
ListenStream=443
</programlisting>

<programlisting>
[Socket]
ListenStream=
ListenStream=7777
ListenStream=192.168.1.1:443
FreeBind=yes
</programlisting>

    <para>NOTE: The first line with an empty value is intentional. <code>systemd</code> allows multiple <code>Listen</code> directives to be declared in a single socket unit; an empty value in a drop-in file resets the list and thus disables the default port 9090 from the original unit.</para>

    <para>The <code>FreeBind</code> option is highly recommended when defining specific IP addresses. See the <ulink url="https://www.freedesktop.org/software/systemd/man/systemd.socket.html"><code>systemd.socket</code> manpage</ulink> for details.</para>

    <para>In order for the changes to take effect, run the following commands:</para>

<programlisting>
$ sudo systemctl daemon-reload
$ sudo systemctl restart cockpit.socket
</programlisting>
{'fraction_non_alphanumeric': 0.09622931240402662, 'fraction_numerical': 0.013137689814024911, 'mean_word_length': 4.210666666666667, 'pattern_counts': {'":': 0, '<': 125, '<?xml version=': 2, '>': 125, 'https://': 4, 'lorem ipsum': 0, 'www.': 6, 'xml': 4}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3177047', 'n_tokens_mistral': 1756, 'n_tokens_neox': 1619, 'n_words': 662}