<?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>

  </section>

  <section id="listen-selinux">
    <title>SELinux Port</title>

    <para>If <ulink url="https://selinuxproject.org/page/Main_Page">SELinux</ulink> is
      protecting your server, then you will need to tell it to allow Cockpit to listen
      on the new port. Run the following command to do so. The last argument specifies
      the desired TCP port.</para>

<programlisting>
$ sudo semanage port -a -t websm_port_t -p tcp 9999
</programlisting>

    <para>If the port is already defined by some other part of the SELinux policy, then
      you will need to use the <code>-m</code> argument to modify the definition. That's
      the case with the <code>443</code> SSL port, which is typically defined as an
      <code>http_port_t</code> port.</para>

<programlisting>
$ sudo semanage port -m -t websm_port_t -p tcp 443
</programlisting>

    <para>The changes should take effect immediately.</para>
  </section>

  <section id="listen-firewalld">
    <title>Firewalld Port</title>

    <para>If <ulink url="https://fedoraproject.org/wiki/FirewallD">Firewalld</ulink> is
      configured as your firewall, then you will need to tell it to allow Cockpit to
      receive connections on the new port. Run the following commands to do so. The last
      options specify the desired TCP port.</para>

<programlisting>
$ sudo firewall-cmd [--zone=ZONE] --add-port=443/tcp
$ sudo firewall-cmd --permanent [--zone=ZONE] --add-port=443/tcp
</programlisting>

  </section>

</chapter>
