mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-24 16:21:56 +00:00
201 lines
12 KiB
HTML
201 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>Expo handbook - Key-Pair Setup</title>
|
|
<link rel="stylesheet" type="text/css" href="/css/main2.css" />
|
|
</head>
|
|
<body>
|
|
<h2 id="tophead">CUCC Expedition Handbook</h2>
|
|
|
|
<h1>Key-Pair Setup</h1>
|
|
<p><var>You only need to do this if you need to do bulk updates of a lot of files to the server.</var> <br> - Copying files <em>from</em> the server does not need this.<br>
|
|
- Only people updating or rearranging files on the server with a <a href="bulkupdatelaptop.html">Bulk Update Laptop</a>, or programmers doing <a href="../troggle/troglaptop.html">troggle software development</a> need this, e.g.
|
|
<ul>
|
|
<li>Editing lots of survex files in the Loser repository
|
|
<li>Moving photographs or Drawing files to the final archive locations
|
|
<li>Programmers working on the troggle code.
|
|
</ul>
|
|
|
|
|
|
<p>As of the server move in spring 2019 you need authorisation on the expo <em>server</em> to log in to get 'programmer access'. (This is not
|
|
the same as logging in to the <em>website</em> as 'expo', which you can do with just the password.) This takes the form of an ssh key. You
|
|
generate a key-pair on the machine you use for access, then send the public half to the server. Once done, all <em>server</em>logins are
|
|
automatic - no passwords needed.</p>
|
|
|
|
<p>'ssh' is 'secure shell' and is widely used for secure access to machines and services.</p>
|
|
|
|
<h2>What do I need to do?</h2>
|
|
<p>You will need to run ssh-keygen/PuTTYgen on your device, email the public key to someone who already has ssh access (Wookey, Paul Fox, Philip Sargent). Once the key is installed by them you should be able to log in as 'expo' over ssh (and other software like git will also use this behind the scenes). This only needs doing once (for any machine you want access from).</p>
|
|
|
|
<p>Our own documentation for <a href="../putty/putty.html">installing PuTTy on Windows</a>.
|
|
|
|
<p>Explanation of <a href="https://www.ssh.com/ssh/keygen/">key-pairs and the ssh-keygen command</a>.</p>
|
|
|
|
<p>A public key file looks like this: <code>ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEApc9+PAMrDtWa8D8/Z<em>..lots more like this..</em>qmkW/cQ== wookey@kh</code>i.e. a long string of characters with 'ssh-rsa' at the start and an ID at the end (often 'user'@'machine').</p>
|
|
|
|
<h3>Windows</h3>
|
|
<p>On Windows 10 or later openssh comes built-in. Open a command terminal and run <tt>ssh</tt> to see if you have it installed. If so just follow the linux instructions on this page - the process is identical. You can install it if it's not there. <a href="https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse">(Microsoft setup instructions)</a>.
|
|
</p>
|
|
<p>Windows 9 has 'WSL' (Windows Subsystem for Linux) which is basically an Ubuntu install. That's the easiest way to use ssh. Run WSL and follow the linux instuctions here.
|
|
</p>
|
|
<p>For older Windows versions you need to use <a href="https://www.ssh.com/ssh/putty/windows/puttygen">puttygen</a>, which is part of <a href="https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html">PuTTY</a>. You need to install that if you don't already have it.</p>
|
|
<p>Follow the Puttygen instructions, but the really short version is:
|
|
<li>Run PuTTYgen</li>
|
|
<li>Click on 'Generate'. Follow the instructions. Don't bother adding a passphrase.</li>
|
|
<li>Type your name in the 'Key comment' field. (just so we know who's key it is)</li>
|
|
<li>Save the private key (this will create a .ppk file that you will need later)</li>
|
|
<li>Don't save the public key - instead copy all of the text from the 'Public key for pasting
|
|
+into OPENSSH authorized_keys file' field, and paste that into the email. Make sure not to miss part or add newlines or otherwise mess with it.</li>
|
|
<li>Run Pageant (it will have been installed in your Start menu, otherwise find it it "C:\Program Files\PuTTY\pageant.exe"). Click the "Add Key" button. Select the .ppk file in the pop-up file list. You only need to do this once.
|
|
</ol>
|
|
|
|
<h3>Linux</h3>
|
|
<ol>
|
|
<li>You need openssh-client installed - it's it extremely likely to already be installed. If not (as root/with sudo)
|
|
<code><font color="darkred">$</font> sudo apt install openssh-client</code>.</li>
|
|
<li>You may already have a key on this machine. If you already have <var>~/.ssh/id_rsa.pub</var>, then send that.</li>
|
|
<li>If not, run
|
|
<code><font color="darkred">$</font> ssh-keygen</code>
|
|
It will ask about setting a password: you can add a password for extra
|
|
security, but a passwordless key is fine, and more convenient. We recommend not adding a password.</li>
|
|
<li>That will create a file called (by default) <var>.ssh/id_rsa.pub</var> in your home directory. Email that file to one of the admins listed above. </li>
|
|
</ol>
|
|
<p>This is an example of the whole interaction where the key file has been given a different name:
|
|
<pre>
|
|
<code><font color="darkred">$</font> <b>ssh-keygen -C "philip@muscogee-wsl"</b>
|
|
Generating public/private rsa key pair.
|
|
Enter file in which to save the key (/home/philip/.ssh/id_rsa): <b>id_rsa_wsl</b>
|
|
Enter passphrase (empty for no passphrase):
|
|
Enter same passphrase again:
|
|
Your identification has been saved in <em>id_rsa_wsl</em>.
|
|
Your public key has been saved in <em>id_rsa_wsl.pub</em>.
|
|
The key fingerprint is:
|
|
SHA256:ySs0YD5IG2ZD50+riUDHWosNq+WJdqpkDlINXh709r0 philip@muscogee-wsl
|
|
The key's randomart image is:
|
|
+---[RSA 2048]----+
|
|
| . o |
|
|
| ..+ . |
|
|
| oB+* + |
|
|
|.=O%.* + o |
|
|
|.+*o= = S . |
|
|
|.* o = . . . |
|
|
|=++.o . . E |
|
|
|B o . |
|
|
|oo |
|
|
+----[SHA256]-----+
|
|
<font color="darkred">$</font>
|
|
</code>
|
|
</pre>
|
|
<p>Once the nerd has told you that the public key is loaded on the server, check that it has worked by logging in to the expo server like this:
|
|
<code>
|
|
<font color="darkred">$</font> <b>ssh expo@expo.survex.com</b>
|
|
</code>
|
|
<h4>If it didn't work</h4>
|
|
<p>You may get this response if the public key has not been loaded properly on the server or if your laptop has not loaded the secret key properly.
|
|
<code>
|
|
expo@expo.survex.com: Permission denied (publickey).
|
|
</code>
|
|
<ol>
|
|
<li>Check that <var>ssh-keygen</var> has put both files into your Linux home <var>.ssh</var> folder on your laptop,
|
|
if not, then move them there:
|
|
<code>
|
|
<font color="darkred">$</font> mv id_rsa_wsl* ~/.ssh
|
|
</code>
|
|
where <b>id_rsa_wsl</b> is the 'file in which to save the key' you specified above. (Other documentation may suggest that this file is called, e.g. 'anathema@mydevice'). But all the files int he .ssh folder must have secure access permissions, e.g. <var>chmod 600 ~/.ssh/*</var>
|
|
<br><br></li>
|
|
<li>Check that the ssh agent process is running and fix it if it is not (full details of how to do this
|
|
give at <a href="https://www.ssh.com/academy/ssh/agent">www.ssh.com/academy/ssh/agent</a>)
|
|
<code>
|
|
<font color="darkred">$</font> ssh-add -l
|
|
</code>
|
|
and if the process is not running, start it like this
|
|
<code>
|
|
<font color="darkred">$</font> eval `ssh-agent`<br />
|
|
<font color="darkred">$</font> ssh-add ~/.ssh/<b>id_rsa_wsl</b><br />
|
|
<font color="darkred">$</font> ssh-add -l
|
|
</code>
|
|
<var>ssh-add -l</var> checks that the key is loaded and the process is running. Now try to login again
|
|
with <var>ssh expo@expo.survex.com</var>.
|
|
|
|
<br><br></li>
|
|
</ol>
|
|
<p>If it still doesn't work, read <href="https://www.ssh.com/academy/ssh/keygen">the online
|
|
documentation</a>, start from scratch, and do it all again but this time using all the defaults and without trying to be clever.
|
|
|
|
<h3>MacOS</h3>
|
|
|
|
<li>Erm, dunno...please fill in</li>
|
|
|
|
<h3>Chromebook</h3>
|
|
|
|
<li>See initial instructions in <a href="chromebook.html">Chromebooks</a> then follow the instructions for Linux here.</li>
|
|
|
|
<h3>Android</h3>
|
|
<ul>
|
|
<li>Install the <a href="https://play.google.com/store/apps/details?id=com.server.auditor.ssh.client&hl=en">Termius app</a>
|
|
which is a ssh client. The free version does ssh but not sFTP. Follow the <a href="https://docs.termius.com/">Termius documentation</a> and in-app help to generate a key pair and then use the same process to upload the public key to the expo server as for Linux machines, i.e. email it to an admin.
|
|
<li>See the expo page on <a href="phone.html">phones</a>.
|
|
</li>
|
|
</ul>
|
|
<h3>iOS</h3>
|
|
<ul>
|
|
<li>There is apparently a version of the <a href="https://play.google.com/store/apps/details?id=com.server.auditor.ssh.client&hl=en">Termius app</a>
|
|
for iPhones. Please try it out and document it here.
|
|
</ul>
|
|
|
|
|
|
|
|
<h2 id="secondmachine">Your second machine</h2>
|
|
<p>OK, you have an uploaded and usable key and you can ssh into the expo server. If you want to connect from another machine (e.g. your phone) it's better to make another key than try to re-use the first one. You don't need a nerd admin now, you can do this yourself. But be <b>extremely careful</b> to follow this exactly. If you innocently rename the files to something that appears more sensible it won't work.
|
|
<ol>
|
|
<li>On your new machine, generate a key-pair. Since you are probably using a different operating system on your second machine, read the instructions above for the relevant OS. Yes you will be generating a new key. Do not re-use the key you had already.
|
|
<li>This time though, you will want to be sure that the key has a meaningful label. On Linux this means something like this:
|
|
<code><font color="darkred">$</font> ssh-keygen -C "anathema.device@pulsifer"</code>
|
|
(if your name is Anathema Device and your new machine is "pulsifer"). Just click through the questions it asks accepting the defaults. It will tell you what the key files are called and where it has put them.
|
|
<li>
|
|
If you accepted the defaults, the public key will be called <var>~/.ssh/id_rsa.pub</var> - check that this is the case.
|
|
<li>Now copy the public key file to your <em>first machine</em>, the one that is already set up with a working key-pair setup with the expo server. Using email to yourself is easiest.
|
|
<li>Now upload the public key. There are 2 ways to do it:
|
|
<ol>
|
|
<li>Using ssh-copy-id
|
|
<li>Using a complex collection of file transfers and file copying and appending
|
|
</ol>
|
|
</ul>
|
|
<h4>Using ssh-copy-id</h4>
|
|
<ul>
|
|
<li>On the first machine which already has a key installed, download the second key from email and rename it as, e.g. <var>pulsifer_id_rsa.pub</var>
|
|
<li>do this command:<br>
|
|
<code>ssh-copy-id -i pulsifer_id_rsa.pub expo@expo.survex.com</code>
|
|
<li>That's it.
|
|
</ul>
|
|
On a Windows machine, Microsoft have not implemented <var>ssh-copy-id</var> so you need to do this instead:
|
|
<ul>
|
|
<li><code>type .ssh\pulsifer_id_rsa.pub | ssh expo@expo.survex.com "cat >> .ssh/authorized_keys"</code>
|
|
</ul>
|
|
<h4>Using Filezilla and file copying</h4>
|
|
<ul>
|
|
<li>using sFTP (Filezilla configured to use sFTP, which uses Pageant by default) to
|
|
<var>expo.survex.com/home/expo/.ssh/keys/</var>
|
|
<li>Now login to the expo server on your first machine and do these commands:<br />
|
|
Be <b>extremely careful</b> to type ">>" and not ">" in the fourth line below otherwise you will delete <i>everyone's</i> logins.
|
|
<code><font color="darkred">$</font> ssh expo@expo.survex.com
|
|
<br /><font color=blue">expo@expo:~$</font> cd .ssh
|
|
<br /><font color=blue">expo@expo:~$</font> cp -p authorized_keys authorized_keys.backup
|
|
<br /><font color=blue">expo@expo:~/.ssh$</font> cat keys/id_rsa.pub >>authorized_keys
|
|
<br /><font color=blue">expo@expo:~/.ssh$</font> tail -n 1 authorized_keys
|
|
</code>
|
|
This adds your key on to the end of the authorized keys list and prints the last line - which should be your key that you just added.
|
|
<p>Note that by using sFTP like this we avoid having to use a text editor over ssh. If you know what you are doing you can do this of course, but the above process is less likely to cause problems for a Windows user setting up their phone as a second device where they are not experienced with vi or nano.
|
|
</ul>
|
|
<li>Now your public key is installed for your second machine. This will enable ssh login instantly. You check that it works by logging into the expo server using ssh from your second machine: <var>ssh expo@expo.survex.com </var>.
|
|
</p>
|
|
|
|
|
|
|
|
|
|
</ol>
|
|
<hr />
|
|
Return to <a href="bulkupdatelaptop.html">Setting up a bulk update laptop</a></body>
|
|
</html>
|