Commit e34b932d authored by Yvan Masson's avatar Yvan Masson
Browse files

Try to fix Markdown syntax

parent e907231f
##########
RemoteHelp
##########
Introduction
============
# RemoteHelpBuilder
RemoteHelpBuilder aims at providing technical people guidelines to build a free
(libre), on-demand system, to help non-technical remote people. It can be seen
......@@ -41,8 +36,7 @@ Many things can be improved, often easily, so feel free to get in touch and
submit pull requests!
Overview
========
# Overview
Once you have configured the system, here is how it works:
......@@ -59,8 +53,7 @@ Once you have configured the system, here is how it works:
server.
Prior warning
=============
# Prior warning
- The setup described here is based on many things at which I am
inexperienced, and has not been reviewed yet: it works but might miss security
......@@ -69,32 +62,29 @@ Prior warning
when security updates are published.
First step
==========
# First step
Download all the files so that you can work easily on them, for example with
Git:
```sh
```
$ cd ~ && git clone https://framagit.org/Yvan-Masson/RemoteHelpBuilder
```
Configuring the intermediate server
===================================
# Configuring the intermediate server
The instructions here target Debian 9 and OpenSSH. Feel free to adapt these to
your particular usage or to your favourite UNIX OS, but be carefull to keep it
secure!
OpenSSH
-------
## OpenSSH
We first create a dedicated user for the SSH connection between the helped and
the intermediate server:
```sh
```
# adduser --home /no-home --no-create-home --shell /bin/false --disabled-login remote-help
```
......@@ -133,19 +123,18 @@ X11Forwarding yes
Finally restart OpenSSH to use the new configuration (if you changed the port
number you will also be deconnected):
```sh
```
# systemctl restart ssh
```
VNC client and helper script
----------------------------
## VNC client and helper script
You can then install the VNC viewer you prefer, but I personnaly install
xtightvncviewer: it is a bit rough but it does not have many dependencies, so it
is great option for a server:
```sh
```
# apt install xtightvncviewer --no-install-recommends
```
......@@ -191,20 +180,19 @@ fi
And make sure that it is executable:
```sh
```
# chmod 755 /usr/local/sbin/remote-help-toggle
```
The above script uses `mkpasswd` command, so we need to install `whois` package
that provides it:
```sh
```
# apt install whois
```
Server's SSH key
----------------
## Server's SSH key
As always, making things securely is a complicated task. Even if the helper and
the helped will be able to mutually authenticate themselves by a phone call when
......@@ -229,8 +217,7 @@ Then, you have to get the server's public key in a format that the SSH client
will understand. We will do that later when preparing the clients.
Client's versionning scheme
===========================
# Client's versionning scheme
Publishing the client software requires to use a proper versionning scheme. To
deal with our specific use case (this project provides some files, you provide
......@@ -243,8 +230,7 @@ you change some string or your icon, the version will be `1.2`. And then if a
new RemoteHelpBuilder's version is published, the version would be `2.2`.
Common clients prerequisites
============================
# Common clients prerequisites
You first need to choose a custom and unique software name, so that the helped:
- understands that only you can make use of this tool to help him,
......@@ -259,14 +245,11 @@ names. The best is to use your custom name chosen above but written in a
in this documentation.
Linux client
============
# Linux client
Prepare the "upstream" release
------------------------------
## Prepare the "upstream" release
Prerequisites
~~~~~~~~~~~~~
### Prerequisites
Create a directory that will contain all your custom files in it. It is easier
to use the "computer friendly" name chosen above, so in this documentation we
......@@ -274,8 +257,7 @@ will use `~/my-remote-help-tool/`. It is advised that you create it in a VCS to
keep track of your changes.
Software icon
~~~~~~~~~~~~~
### Software icon
This is optionnal, but you can provide your own icon. If you do, I recommend
that you use the computer friendly name chosen above, so this examples uses
......@@ -303,8 +285,7 @@ on the sizes:
```
Desktop entry
~~~~~~~~~~~~~
### Desktop entry
The desktop entry file will make your software appear in the helped desktop
menu. This file will be saved in
......@@ -338,18 +319,17 @@ Do not hesitate to read the
if you have any question regarding this file.
Software, strings and parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Software, strings and parameters
First copy the client software/script to include it in your upstream release:
```sh
```
cp ~/RemoteHelpBuilder/Linux-client/linux-client ~/my-remote-help-tool/my-remote-help-tool
```
Then copy the template containing variables that the client script will use:
```sh
```
cp ~/RemoteHelpBuilder/Linux-client/variables ~/my-remote-help-tool/variables
```
......@@ -361,15 +341,14 @@ and to escape quotes with backslashes (`\"`). You can use `\n` or `\t`.
Ensure these two files have execute rights.
Intermediate server's SSH public key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Intermediate server's SSH public key
As said earlier, we also include the server's public key, ed25519 in this
document. In the following command, be sure to use the IP address of you server
or its FQDN exactly the same way that you wrote it in
`~/my-remote-help-tool/linux-strings.sh` (otherwise the client will not use it):
```sh
```
$ ssh-keyscan -t ed25519 <you server's IP address or FQDN> > ~/my-remote-help-tool/ssh-server-public-key
```
......@@ -379,8 +358,7 @@ For more information on this file formate see `SSH_KNOWN_HOSTS FILE FORMAT`
section in `man 8 sshd`.
Building the Debian and derivatives package
-------------------------------------------
## Building the Debian and derivatives package
Below instructions are very simple: do not hesitate to read the dedicated
chapter of the excellent
......@@ -393,7 +371,7 @@ with Debian packaging: it works but it should certainely be improved.
Building a Debian package requires that you install `build-essential` and is
made easier by using tools from `dh_make` and `devscripts`:
```sh
```
# apt install build-essential dh_make devscripts
```
......@@ -401,14 +379,14 @@ First make a copy of your source directory `~/my-remote-help-tool/` to include
the version number. This "simulates" an upstream release. The first time you
build your package, you will probably do:
```sh
```
$ cp -r ~/my-remote-help-tool/ ~/my-remote-help-tool-1.1/
```
Go inside this directory and generate all files needed for proper packaging
(replace the content in brackets to match your name/company and e-mail):
```sh
```
cd ~/my-remote-help-tool-1.1 && \
DEBFULLNAME="<your name>" dh_make \
--copyright gpl3 \
......@@ -420,7 +398,7 @@ DEBFULLNAME="<your name>" dh_make \
Many useless files have been created in the `debian/` subdirectory, so we delete
them:
```sh
```
$ cd debian && rm manpage.* menu.ex postinst.ex postrm.ex preinst.ex prerm.ex README.Debian README.source *.cron.d.ex *.doc-base.EX *-docs.docs watch.ex
```
......@@ -454,7 +432,7 @@ icons/scalable/my-remote-help-tool.svgz usr/share/icons/hicolor/scalable/app
Finaly, go back to `~/my-remote-help-tool-1.1/` and build the package:
```sh
```
$ dpkg-buildpackage --unsigned-source --unsigned-changes
```
......@@ -466,11 +444,9 @@ Be carefull to keep/backup `~/my-remote-help-tool-1.1/`: you will use it if you
need to build a new version of you package.
Update the Debian and derivatives package
-----------------------------------------
## Update the Debian and derivatives package
When you need to fix packaging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### When you need to fix packaging
If you change any file in `~/my-remote-help-tool-<some_version>/debian` you need
to rebuild the package.
......@@ -481,25 +457,24 @@ to rebuild the package.
Edit the changelog (`--no-auto-nmu` ensure a proper version number even if the
email or full name are different from previous release):
```sh
```
$ DEBFULLNAME=<your name> DEBEMAIL=<your email> debchange --no-auto-nmu --rebuild
```
Finalize the changelog:
```sh
```
$ DEBFULLNAME=<your name> DEBEMAIL=<your email> debchange --no-auto-nmu --release ""
```
And rebuild the package:
```sh
```
$ dpkg-buildpackage --unsigned-source --unsigned-changes
```
For everything else
~~~~~~~~~~~~~~~~~~~
### For everything else
When there is a new version of RemoteHelpBuilder that you want to use, or if you
need to change one of your files (`variables`, `ssh-server-public-key` or
......@@ -508,7 +483,7 @@ need to change one of your files (`variables`, `ssh-server-public-key` or
Copy the directory of the last 'upstream version' and increment the version, for
example:
```sh
```
cp -r ~/my-remote-help-tool-1.1 ~/my-remote-help-tool-1.2
```
......@@ -517,31 +492,28 @@ not forget to adapt `~/my-remote-help-tool-1.2/debian/` files if needed.
Inside this new directory, edit the changelog:
```sh
```
$ DEBFULLNAME=<your name> DEBEMAIL=<your email> debchange --from-dir-name
```
Finalize the changelog:
```sh
```
$ DEBFULLNAME=<your name> DEBEMAIL=<your email> debchange --no-auto-nmu --release ""
```
And rebuild the package:
```sh
```
$ dpkg-buildpackage --unsigned-source --unsigned-changes
```
Building the Windows client
===========================
# Building the Windows client
First Build
-----------
## First Build
Prerequisites
~~~~~~~~~~~~~
### Prerequisites
This requires the use of a Windows computer.
......@@ -554,8 +526,7 @@ Also, ensure you have access to files inside the `Windows-client` directory of
RemoteHelpBuilder.
PuTTY
~~~~~
### PuTTY
From the
[PuTTY website](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html),
......@@ -569,8 +540,7 @@ Create in this same directory a file called `version.txt` and write inside the
version (for example `0.71`), so that you and the user can easily retrieve it.
UltraVNC
~~~~~~~~
### UltraVNC
From the [UltraVNC website](http://www.uvnc.com), download the 32 bits version
and save it anywhere on Windows computer. Run the installer, which should be
......@@ -599,14 +569,13 @@ Notes:
straightforward.
Wrapper script and variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### Wrapper script and variables
Putty (and so plink.exe) does not use the same format as OpenSSH does for SSH
public keys. To get your intermediate server's public key from Windows (or from
Linux using Wine), run:
```sh
```
plink.exe -v -batch -P <ssh port> <FQDN or IP address>>
```
......@@ -617,7 +586,7 @@ If you chose a signature algorithm other than ed25519, like RSA, you can get the
same line from a Linux computer by converting the _known host_ file used for
building the Linux client:
```sh
```
printf "ssh-rsa "; ssh-keygen -l -E md5 -f ~/my-remote-help-tool/ssh-server-public-key | sed 's/MD5://' | cut -d " " -f -2
```
......@@ -628,15 +597,13 @@ VBScript, see example values for quoting and line returns.
Also, do not hesitate to add your copyright at the beginning of the file.
Licence
~~~~~~~
### Licence
Copy `Windows-client\Licence.txt` and `Windows-client\Changelog.txt` to
`my-remote-help-tool\Sources\`.
Software icon
~~~~~~~~~~~~~
### Software icon
If you want, you can provide you own icon for the software: it will be used by
the installer and for the desktop and application menu shortcuts. Personnally
......@@ -644,8 +611,7 @@ I use GIMP to export my icon in 256x256 px in the .ico format. Save it in
`my-remote-help-tool\Sources\`.
Building with InnotSetup
~~~~~~~~~~~~~~~~~~~~~~~~
### Building with InnotSetup
To create the Windows installer, you will have to download the Windows libre
software [Inno Setup](http://www.jrsoftware.org/isinfo.php). Of course, you can
......@@ -666,8 +632,7 @@ Once done, click on the "Compile" button and your installer will appear in
Wine).
Build a new client version
--------------------------
## Build a new client version
When a new version of RemoteHelpBuilder improves the VBScript (fortunately it
will happen!), when PuTTY or UltraVNC release a security update, or when you
......@@ -679,8 +644,7 @@ want to improve the InnoSetup installer, you need to build a new client version.
- Compile the installer with InnoSetup.
Usage
=====
# Usage
Finally the easy part!
......@@ -697,8 +661,7 @@ Finally the easy part!
3. When done, disable the remote-help user: `sudo remote-help-toggle disable`
Release policy
==============
# Release policy
A new release is published when commits modify one of the provided files of
Windows or Linux client (except when modification is only on examples, comments
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment