<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.docbook.org/xml/4.4/docbookx.dtd">
<article>
  <articleinfo>
    <title>FreedomBox/Manual/SecureShell</title>
    <revhistory>
      <revision>
        <revnumber>11</revnumber>
        <date>2018-01-30 07:55:33</date>
        <authorinitials>SunilMohanAdapa</authorinitials>
        <revremark>Update GitHub links with Salsa</revremark>
      </revision>
      <revision>
        <revnumber>10</revnumber>
        <date>2017-03-06 23:17:08</date>
        <authorinitials>JamesValleroy</authorinitials>
        <revremark>add note</revremark>
      </revision>
      <revision>
        <revnumber>9</revnumber>
        <date>2016-10-13 21:49:06</date>
        <authorinitials>David Jones</authorinitials>
        <revremark>Added infromation about connecting to the FBX using ssh over Tor</revremark>
      </revision>
      <revision>
        <revnumber>8</revnumber>
        <date>2016-10-13 21:09:31</date>
        <authorinitials>David Jones</authorinitials>
        <revremark>Added information about admin account for first log in to Plinth</revremark>
      </revision>
      <revision>
        <revnumber>7</revnumber>
        <date>2016-09-05 09:42:36</date>
        <authorinitials>ElVirolo</authorinitials>
        <revremark>Removing my previous contribution, as info already present in original version.</revremark>
      </revision>
      <revision>
        <revnumber>6</revnumber>
        <date>2016-09-05 09:39:05</date>
        <authorinitials>ElVirolo</authorinitials>
      </revision>
      <revision>
        <revnumber>5</revnumber>
        <date>2016-09-05 09:26:15</date>
        <authorinitials>ElVirolo</authorinitials>
        <revremark>Added "Users created via Plinth" paragraph</revremark>
      </revision>
      <revision>
        <revnumber>4</revnumber>
        <date>2015-12-21 19:42:10</date>
        <authorinitials>JamesValleroy</authorinitials>
        <revremark>update default account</revremark>
      </revision>
      <revision>
        <revnumber>3</revnumber>
        <date>2015-12-21 19:33:56</date>
        <authorinitials>JamesValleroy</authorinitials>
        <revremark>fix outline level</revremark>
      </revision>
      <revision>
        <revnumber>2</revnumber>
        <date>2015-12-15 19:31:18</date>
        <authorinitials>PhilippeBaret</authorinitials>
        <revremark>Added definition title</revremark>
      </revision>
      <revision>
        <revnumber>1</revnumber>
        <date>2015-09-16 16:22:37</date>
        <authorinitials>SunilMohanAdapa</authorinitials>
        <revremark>New manual page for secure shell access</revremark>
      </revision>
    </revhistory>
  </articleinfo>
  <section>
    <title>Secure Shell</title>
    <section>
      <title>What is Secure Shell?</title>
      <para>FreedomBox runs <code>openssh-server</code> server by default allowing remote logins from all interfaces.  If your hardware device is connected to a monitor and a keyboard, you may login directly as well.  Regular operation of FreedomBox does not require you to use the shell.  However, some tasks or identifying a problem may require you to login to a shell. </para>
    </section>
    <section>
      <title>Setting Up A User Account</title>
      <section>
        <title>Plinth First Log In: Admin Account</title>
        <para>When creating an account in Plinth for the first time, this user will automatically have administrator capabilities. <code>Admin</code> users are able to log in using ssh (see Logging In below) and have superuser privileges via sudo. </para>
      </section>
      <section>
        <title>Default User Account</title>
        <itemizedlist>
          <listitem>
            <para>Note: If you can access Plinth, then you don't need to do this. You can use the user account created in Plinth to connect to SSH. </para>
          </listitem>
        </itemizedlist>
        <para>The pre-built FreedomBox images have a default user account called "fbx". However the password is not set for this account, so it will not be possible to log in with this account by default. </para>
        <para>There is a script included in the freedom-maker program, that will allow you to set the password for this account, if it is needed. To set a password for the "fbx" user: </para>
        <para>1. Decompress the image file. </para>
        <para>2. Get a copy of freedom-maker from <ulink url="https://salsa.debian.org/freedombox-team/freedom-maker/"/>. </para>
        <para>3. Run <code>sudo ./bin/passwd-in-image &lt;image-file&gt; fbx</code>. </para>
        <para>4. Copy the image file to SD card and boot device as normal. </para>
        <para>The "fbx" user also has superuser privileges via sudo. </para>
      </section>
    </section>
    <section>
      <title>Logging In</title>
      <section>
        <title>Local</title>
        <para>To login via SSH, to your FreedomBox: </para>
        <screen><![CDATA[$ ssh fbx@freedombox]]></screen>
        <para>Replace <code>fbx</code> with the name of the user you wish to login as.  <code>freedombox</code> should be replaced with the hostname or IP address of you FreedomBox device as found in the <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Manual/QuickStart#">Quick Start</ulink> process. </para>
        <para><code>fbx</code> is the default user present on FreedomBox with superuser privileges.  Any other user created using Plinth and belonging to the group <code>admin</code> will be able to login.  The <code>root</code> account has no password set and will not be able to login.  Access will be denied to all other users. </para>
        <para><code>fbx</code> and users in <code>admin</code> group will also be able to login on the terminal directly.  Other users will be denied access. </para>
        <para>If you repeatedly try to login as a user and fail, you will be blocked from logging in for some time.  This is due to <code>libpam-abl</code> package that FreedomBox installs by default.  To control this behavior consult <code>libpam-abl</code> documentation. </para>
      </section>
      <section>
        <title>SSH over Tor</title>
        <para>If in Plinth you have enabled hidden services via Tor, you can access your <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox#">FreedomBox</ulink> using ssh over Tor. On a GNU/Linux computer, install netcat-openbsd. </para>
        <screen><![CDATA[$ sudo apt-get install netcat-openbsd]]></screen>
        <para>Edit ~/.ssh/config to enable connections over Tor. </para>
        <screen><![CDATA[$ nano ~/.ssh/config]]></screen>
        <para>Add the following: </para>
        <screen><![CDATA[Host *.onion
  user USERNAME
  port 22
  ProxyCommand nc -X 5 -x 127.0.0.1:9050 %h %p]]></screen>
        <para>Replace USERNAME with, e.g., an <code>admin</code> username (see above). </para>
        <para>Note that in some cases you may need to replace 9050 with 9150. </para>
        <para>Now to connect to the <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox#">FreedomBox</ulink>, open a terminal and type: </para>
        <screen><![CDATA[$ ssh USERNAME@ADDRESS.onion]]></screen>
        <para>Replace USERNAME with, e.g., an <code>admin</code> username, and ADDRESS with the hidden service address for your <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox#">FreedomBox</ulink>. </para>
      </section>
    </section>
    <section>
      <title>Becoming Superuser</title>
      <para>After logging in, if you want to become the superuser for performing administrative activities: </para>
      <screen><![CDATA[$ sudo su]]></screen>
      <para>Make a habit of logging in as root <emphasis>only when you need to</emphasis>.  If you aren't logged in as root, you can't accidentally break everything. </para>
      <para>
        <anchor id="changingpassword"/>
      </para>
    </section>
    <section>
      <title>Changing Password</title>
      <para>To change the password of a user managed by Plinth, use the change password page.  However, the <code>fbx</code> default user is not managed by Plinth and its password cannot be changed in the web interface. </para>
      <para>To change password on the terminal, log in to your FreedomBox as the user whose password you want to change. Then, run the following command: </para>
      <screen><![CDATA[$ passwd]]></screen>
      <para>This will ask you for your current password before giving you the opportunity to set a new one. </para>
      <!--rule (<hr>) is not applicable to DocBook-->
      <informaltable>
        <tgroup cols="8">
          <colspec colname="col_0"/>
          <colspec colname="col_1"/>
          <colspec colname="col_2"/>
          <colspec colname="col_3"/>
          <colspec colname="col_4"/>
          <colspec colname="col_5"/>
          <colspec colname="col_6"/>
          <colspec colname="col_7"/>
          <tbody>
            <row rowsep="1">
              <entry colsep="1" rowsep="1">
                <para>
                  <emphasis role="strong">Information</emphasis>
                </para>
              </entry>
              <entry colsep="1" rowsep="1"/>
              <entry colsep="1" rowsep="1"/>
              <entry colsep="1" rowsep="1">
                <para>
                  <emphasis role="strong">Support</emphasis>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <emphasis role="strong">Work Space</emphasis>
                </para>
              </entry>
              <entry colsep="1" rowsep="1"/>
              <entry colsep="1" rowsep="1">
                <para>
                  <emphasis role="strong">Reports</emphasis>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <emphasis role="strong">Promote</emphasis>
                </para>
              </entry>
            </row>
            <row rowsep="1">
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Introduction#">Overview</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Hardware#">Hardware</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <emphasis role="strong"> </emphasis>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Support#">Live Help</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Contribute#">Where To Start</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Translate#">Translate</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/ProgressCalls#">Calls</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/TalksAndPresentations#">Talks</ulink>
                </para>
              </entry>
            </row>
            <row rowsep="1">
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Features#">Features</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Vision#">Vision</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <emphasis role="strong"> </emphasis>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/QuestionsAndAnswers#">Q&amp;A</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Design#">Design</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/TODO#">To Do</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Metrics#">Metrics</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Press#">Press</ulink>
                </para>
              </entry>
            </row>
            <row rowsep="1">
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Download#">Download</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Manual#">Manual</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <emphasis role="strong"> </emphasis>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/UserExperience#">Use cases</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Contribute/Code#">Code</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Contributors#">Contributors</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/ReleaseNotes#">Releases</ulink>
                </para>
              </entry>
              <entry colsep="1" rowsep="1">
                <para>
                  <ulink url="https://wiki.debian.org/FreedomBox/Manual/SecureShell/FreedomBox/Blog#">Blog</ulink>
                </para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
      <!--rule (<hr>) is not applicable to DocBook-->
      <para>
      </para>
    </section>
  </section>
</article>
