README.md 27.2 KB
Newer Older
Yvan Masson's avatar
Yvan Masson committed
1
# RemoteHelpBuilder
Yvan Masson's avatar
Yvan Masson committed
2
3
4

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
Yvan Masson's avatar
Yvan Masson committed
5
as a basic alternative to TeamViewer©, but based on VNC and SSH existing
Yvan Masson's avatar
Yvan Masson committed
6
7
implementations.

Yvan Masson's avatar
Yvan Masson committed
8
9
10
11
You need to set it up once (configuring the "_intermediate server_", customizing
and packaging a little "_client software_" intended for the "_helped_"), and you
can then easily provide help to non-tech people running Windows (≥ XP) or Linux
(currently Debian ≥ 8, Ubuntu ≥ 16.04 and Linux Mint ≥ 18.0).
Yvan Masson's avatar
Yvan Masson committed
12
13


Yvan Masson's avatar
Yvan Masson committed
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# Table of contents

- [Overview](#overview)
- [Prior warning](#prior-warning)
- [First step](#first-step)
- [Configuring the intermediate server](#configuring-the-intermediate-server)
    - [OpenSSH](#openssh)
    - [VNC client and helper script](#vnc-client-and-helper-script)
    - [Server's SSH key](#servers-ssh-key)
- [Client's versionning scheme](#clients-versionning-scheme)
- [Common clients prerequisites](#common-clients-prerequisites)
- [Linux client](#linux-client)
    - [Prepare the "upstream" release](#prepare-the-upstream-release)
        - [Prerequisites](#prerequisites)
        - [Software icon](#software-icon)
        - [Desktop entry](#desktop-entry)
        - [Software, strings and parameters](#software-strings-and-parameters)
Yvan Masson's avatar
Yvan Masson committed
31
        - [Intermediate server's SSH public key](#intermediate-servers-ssh-public-key)
Yvan Masson's avatar
Yvan Masson committed
32
    - [First build of the Debian and derivatives package](#first-build-of-the-debian-and-derivatives-package)
Yvan Masson's avatar
Yvan Masson committed
33
34
35
36
37
38
39
40
41
    - [Update the Debian and derivatives package](#update-the-debian-and-derivatives-package)
        - [When you need to fix packaging](#when-you-need-to-fix-packaging)
        - [For everything else](#for-everything-else)
- [Building the Windows client](#building-the-windows-client)
    - [First Build](#first-build)
        - [Prerequisites](#prerequisites-1)
        - [PuTTY](#putty)
        - [UltraVNC](#ultravnc)
        - [Wrapper script and variables](#wrapper-script-and-variables)
Yvan Masson's avatar
Yvan Masson committed
42
        - [license](#license)
Yvan Masson's avatar
Yvan Masson committed
43
        - [Software icon](#software-icon-1)
Yvan Masson's avatar
Yvan Masson committed
44
        - [Building with InnoSetup](#building-with-innosetup)
Yvan Masson's avatar
Yvan Masson committed
45
    - [Building a new client version](#building-a-new-client-version)
Yvan Masson's avatar
Yvan Masson committed
46
47
- [Usage](#usage)
- [Release policy](#release-policy)
Yvan Masson's avatar
Yvan Masson committed
48
49
50
- [Frequently asked questions](#frequently-asked-questions)
    - [Icon is not displayed when running the Linux client](icon-is-not-displayed-when-running-the-Linux-client)
    - [How to run the VNC client on your computer and not on the server](how-to-run-the-VNC-client-on-your-computer-and-not-on-the-server)
Yvan Masson's avatar
Yvan Masson committed
51
- [License](#license)
Yvan Masson's avatar
Yvan Masson committed
52

Yvan Masson's avatar
Yvan Masson committed
53

Yvan Masson's avatar
Yvan Masson committed
54
# Overview
Yvan Masson's avatar
Yvan Masson committed
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

Once you have configured the system, here is how it works:

1. Get in touch with the helped (usually by phone) to help him to get and
   install the client software. Even computer beginners should be able to
   install it.
2. Connect to the intermediate server with SSH and X11 forwarding to generate a
   one-time password, and give it to the helped.
3. The helped starts the client software, types the password and validates: this
   initiates SSH port forwarding to the intermediate server and starts a
   VNC server.
3. Start the VNC client on the intermediate server and provide help!
4. When done, disable the one-time password and log out from the intermediate
   server.

Yvan Masson's avatar
Yvan Masson committed
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
Requirements:

- You must be confident with the Linux command line and system administration to
  be able to build the system and to understand the security implications
  (hopefully the instructions are clear enough).
- You needs an intermediate server, with root access, that can be joined on its
  SSH port from the Internet (it can be a hosted VPS or a Raspberry Pi behind a
  personnal modem/router). It needs either a static IP address or to be pointed
  to by DNS. You could eventually use your own Linux computer to act as the
  intermediate server. Only trusted users must have access to this server.
- You must distribute the client software to the helped before first use.
- SSH must not be blocked by a firewall somewhere in the path (SSH port number
  can be chosen).
- You and the helped need a bare minimum of 1 Mbit/s ADSL connection, but
  2 Mbit/s is advised.
  
Limitations:

- This system does not allow helping more than one person at the same time.
- Wayland Linux clients are not supported.

Many things can be improved, often easily, so feel free to get in touch and
submit pull requests!

Yvan Masson's avatar
Yvan Masson committed
94

Yvan Masson's avatar
Yvan Masson committed
95
# Prior warning
Yvan Masson's avatar
Yvan Masson committed
96
97

- The setup described here is based on many things at which I am
Yvan Masson's avatar
Yvan Masson committed
98
99
  inexperienced, and has not been reviewed yet: it works but might contain
  security issues.
Yvan Masson's avatar
Yvan Masson committed
100
101
102
103
- The Windows client embeds Putty and UltraVNC, so you must update this client
  when security updates are published.


Yvan Masson's avatar
Yvan Masson committed
104
# First step
Yvan Masson's avatar
Yvan Masson committed
105
106
107
108

Download all the files so that you can work easily on them, for example with
Git:

Yvan Masson's avatar
Yvan Masson committed
109
```
Yvan Masson's avatar
Yvan Masson committed
110
$ cd ~ && git clone https://framagit.org/Yvan-Masson/RemoteHelpBuilder.git
Yvan Masson's avatar
Yvan Masson committed
111
112
113
```


Yvan Masson's avatar
Yvan Masson committed
114
# Configuring the intermediate server
Yvan Masson's avatar
Yvan Masson committed
115
116
117
118
119
120

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!


Yvan Masson's avatar
Yvan Masson committed
121
## OpenSSH
Yvan Masson's avatar
Yvan Masson committed
122
123
124
125

We first create a dedicated user for the SSH connection between the helped and
the intermediate server:

Yvan Masson's avatar
Yvan Masson committed
126
```
Yvan Masson's avatar
Yvan Masson committed
127
128
129
130
131
132
133
134
135
# adduser --home /no-home --no-create-home --shell /bin/false --disabled-login remote-help
```

We then need to allow the helped to initiate SSH port forwarding and to prevent
him from doing anything else. Add the following section in
`/etc/ssh/sshd_config`:

```
Match User remote-help
Yvan Masson's avatar
Yvan Masson committed
136
137
138
139
140
141
142
143
    AllowAgentForwarding no
    AllowTcpForwarding yes
    AuthenticationMethods "password"
    ForceCommand echo 'This account can only be used for VNC port forwarding'
    PermitOpen localhost:5900
    PermitTunnel no
    PermitTTY no
    X11Forwarding no
Yvan Masson's avatar
Yvan Masson committed
144
145
146
147
148
149
150
151
152
153
```

Optionnaly, you can change in the above file the port OpenSSH listens on (some
firewall between the server and the helped may block TCP port 22). Here, we
choose to listen on port 80 that is normally never blocked:

```
Port 80
```

Yvan Masson's avatar
Yvan Masson committed
154
155
To keep the server setup simple and still secure, the VNC client will be run
directly on the server. Ensure that X11 forwarding is enabled on the server,
Yvan Masson's avatar
Yvan Masson committed
156
157
158
159
160
161
162
163
164
either globally or for your specific user, still in `/etc/ssh/sshd_config`:

```
X11Forwarding yes
```

Finally restart OpenSSH to use the new configuration (if you changed the port
number you will also be deconnected):

Yvan Masson's avatar
Yvan Masson committed
165
```
Yvan Masson's avatar
Yvan Masson committed
166
167
168
169
# systemctl restart ssh
```


Yvan Masson's avatar
Yvan Masson committed
170
## VNC client and helper script
Yvan Masson's avatar
Yvan Masson committed
171
172
173
174
175

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:

Yvan Masson's avatar
Yvan Masson committed
176
```
Yvan Masson's avatar
Yvan Masson committed
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
# apt install xtightvncviewer --no-install-recommends
```

We now install on the server an optionnal little script that facilitates :

- Enabling the `remote-help` user with a random 4 digits password.
- Remembering of the `xtightvncviewer` command line to start the VNC client.
- Disabling the `remote-help` user so that the helped can not login anymore on
  your server.

Put this script in `/usr/local/sbin/remote-help-toggle`:

```sh
#!/bin/sh

if ! [ "$(id --user)" = "0" ]; then
    echo "Must be run as root"; exit
fi

the_user="remote-help"

if [ "$1" = "enable" ]; then
    # generates password
    pwd=$(shuf -i 1000-9999 -n 1)
    # encrypt it for /etc/shadow
    encpwd=$(echo "$pwd" | mkpasswd --method=sha-512 --stdin)
    usermod --password "$encpwd" "$the_user"
    echo "Password : $pwd"
    echo "To start VNC viewer, from server's network (uncompressed):"
    echo "  xtightvncviewer -encodings \"tight\" -compresslevel 1 -quality 0 localhost"
    echo "To start VNC viewer from another network (compressed):"
    echo "  xtightvncviewer -encodings \"tight\" -compresslevel 9 -quality 0 localhost"
    echo "Use password \"foo\" for Windows computers."

elif [ "$1" = "disable" ]; then
    passwd --lock "$the_user" && echo "Password login for user \"$the_user\" disabled"

else
    echo "Usage : $0 enable|disable"
fi

```

And make sure that it is executable:

Yvan Masson's avatar
Yvan Masson committed
222
```
Yvan Masson's avatar
Yvan Masson committed
223
224
225
226
227
228
# chmod 755 /usr/local/sbin/remote-help-toggle
```

The above script uses `mkpasswd` command, so we need to install `whois` package
that provides it:

Yvan Masson's avatar
Yvan Masson committed
229
```
Yvan Masson's avatar
Yvan Masson committed
230
231
232
233
# apt install whois
```


Yvan Masson's avatar
Yvan Masson committed
234
## Server's SSH key
Yvan Masson's avatar
Yvan Masson committed
235

Yvan Masson's avatar
Yvan Masson committed
236
237
238
239
As always, making things securely is a complicated task. Even if the helped and
you will be able to mutually authenticate by a phone call when transmitting the
one-time password, it can be a good thing for the client software to also
authenticate the SSH server with its public key.
Yvan Masson's avatar
Yvan Masson committed
240
241
242
243
244
245
246
247
248
249
250

Your server probably provides different signature algorithms, and corresponding
public and private keys are stored in `/etc/ssh/ssh_host_*` files. To simplify
the setup, we will pick only one, ed25519. As I understand it, this is a purely
subjective choice, feel free to choose another one (there does not seem to be
good or bad choice, see for example
[this stackexchange thread](https://security.stackexchange.com/questions/50878/ecdsa-vs-ecdh-vs-ed25519-vs-curve25519)).
However, ed25519 public key is easier to get from Windows.

Practically, this means you will have to keep a backup of the public and
corresponding private key in case of a disaster, failing that you would have to
Yvan Masson's avatar
Yvan Masson committed
251
252
make a new release of the Windows and Linux client including the new public key.
As we use ed25519, backup `/etc/ssh/ssh_host_ed25519_key` and
Yvan Masson's avatar
Yvan Masson committed
253
254
255
256
257
258
`/etc/ssh/ssh_host_ed25519_key.pub` and keep it in a secure place.

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.


Yvan Masson's avatar
Yvan Masson committed
259
# Client's versionning scheme
Yvan Masson's avatar
Yvan Masson committed
260
261
262
263

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
others), I recommend you use two numbers separated by a `.`:
Yvan Masson's avatar
Yvan Masson committed
264

Yvan Masson's avatar
Yvan Masson committed
265
266
267
268
269
270
271
272
- the RemoteHelpBuilder version,
- the version of your settings.

So for the first time you build the package, the version will be `1.1`. If then
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`.


Yvan Masson's avatar
Yvan Masson committed
273
# Common clients prerequisites
Yvan Masson's avatar
Yvan Masson committed
274
275

You first need to choose a custom and unique software name, so that the helped:
Yvan Masson's avatar
Yvan Masson committed
276

Yvan Masson's avatar
Yvan Masson committed
277
278
- understands that only you can make use of this tool to help him,
- can eventually install more than one software like yours.
Yvan Masson's avatar
Yvan Masson committed
279

Yvan Masson's avatar
Yvan Masson committed
280
281
282
283
284
285
286
287
288
289
This documentation assumes that this name is "My remote help tool". Replace it
with the name you chose everytime you see it in this documentation.

You then need to find the name that will be used for the program and package
names. The best is to use your custom name chosen above but written in a
"computer friendly" way. In this documentation we will use
`my-remote-help-tool`. Replace it with the name you chose everytime you see it
in this documentation.


Yvan Masson's avatar
Yvan Masson committed
290
# Linux client
Yvan Masson's avatar
Yvan Masson committed
291

Yvan Masson's avatar
Yvan Masson committed
292
## Prepare the "upstream" release
Yvan Masson's avatar
Yvan Masson committed
293

Yvan Masson's avatar
Yvan Masson committed
294
### Prerequisites
Yvan Masson's avatar
Yvan Masson committed
295
296
297
298
299
300
301

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
will use `~/my-remote-help-tool/`. It is advised that you create it in a VCS to
keep track of your changes.


Yvan Masson's avatar
Yvan Masson committed
302
### Software icon
Yvan Masson's avatar
Yvan Masson committed
303
304
305
306
307
308
309
310
311

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
"my-remote-help-tool".

You can provide one or many sizes so that the desktop environment can pick the
best size for the user. You can have a look at what sizes and formats are
usually provided on Debian and derivatives by looking in `/usr/share/icons/`. If
you target Gnome, you should probably read the
Yvan Masson's avatar
Yvan Masson committed
312
[Gnome guidelines](https://developer.gnome.org/hig/3.32/icons-and-artwork.html.en).
Yvan Masson's avatar
Yvan Masson committed
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329

If you want to provide an icon, you can put it in the following layout depending
on the sizes:

```
~/my-remote-help-tool/icons/
  ├── 48x48
  │   └── my-remote-help-tool.png
  ├── 256x256
  │   └── my-remote-help-tool.png
  ├── 512x512
  │   └── my-remote-help-tool.png
  └── scalable
      └── my-remote-help-tool.svgz
```


Yvan Masson's avatar
Yvan Masson committed
330
### Desktop entry
Yvan Masson's avatar
Yvan Masson committed
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351

The desktop entry file will make your software appear in the helped desktop
menu. This file will be saved in
`~/my-remote-help-tool/my-remote-help-tool.desktop` and can be based on this
example:

```
[Desktop Entry]
Name=My remote help tool
Name[fr]=Mon outil d'aide à distance
Comment=Enable remote help
Comment[fr]=Active l'aide à distance
Exec=my-remote-help-tool
Terminal=false
Categories=Utility
Type=Application
Icon=my-remote-help-tool
StartupNotify=true
```

Be carefull to customize:
Yvan Masson's avatar
Yvan Masson committed
352

Yvan Masson's avatar
Yvan Masson committed
353
354
355
356
357
358
359
360
361
362
363
364
- The `Name`(s) and `Comment`(s) to match what the helped needs to see.
- The `Exec` line to match your Debian package name.
- The `Icon` line :
  - to match the name of your icon,
  - or to match the name of an icon that is already on the helped computer,
    probably in `/usr/share/icons/`.

Do not hesitate to read the
[desktop entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html)
if you have any question regarding this file.


Yvan Masson's avatar
Yvan Masson committed
365
### Software, strings and parameters
Yvan Masson's avatar
Yvan Masson committed
366

Yvan Masson's avatar
Yvan Masson committed
367
368
First copy the client software/script to include it in your upstream release
(remember to replace `my-remote-help-tool` by the name you chose previously):
Yvan Masson's avatar
Yvan Masson committed
369

Yvan Masson's avatar
Yvan Masson committed
370
```
Yvan Masson's avatar
Yvan Masson committed
371
372
373
374
375
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:

Yvan Masson's avatar
Yvan Masson committed
376
```
Yvan Masson's avatar
Yvan Masson committed
377
378
379
380
381
382
383
384
385
386
387
cp ~/RemoteHelpBuilder/Linux-client/variables ~/my-remote-help-tool/variables
```

You must now edit `~/my-remote-help-tool/variables` to suit your
needs. All variables in this shell script will be used to feed the main script,
`linux-client`. As usual in shell scripts, be very careful to quote variables
and to escape quotes with backslashes (`\"`). You can use `\n` or `\t`.

Ensure these two files have execute rights.


Yvan Masson's avatar
Yvan Masson committed
388
### Intermediate server's SSH public key
Yvan Masson's avatar
Yvan Masson committed
389
390

As said earlier, we also include the server's public key, ed25519 in this
Yvan Masson's avatar
Yvan Masson committed
391
example. In the following command, be sure to use the IP address of you server
Yvan Masson's avatar
Yvan Masson committed
392
393
394
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):

Yvan Masson's avatar
Yvan Masson committed
395
```
Yvan Masson's avatar
Yvan Masson committed
396
$ ssh-keyscan -t ed25519 <you server's FQDN or IP address> > ~/my-remote-help-tool/ssh-server-public-key
Yvan Masson's avatar
Yvan Masson committed
397
398
399
400
```

If you changed the port SSH listens on, use the `-p` option.

Yvan Masson's avatar
Yvan Masson committed
401
For more information on this file format see `SSH_KNOWN_HOSTS FILE FORMAT`
Yvan Masson's avatar
Yvan Masson committed
402
403
404
section in `man 8 sshd`.


Yvan Masson's avatar
Yvan Masson committed
405
## First build of the Debian and derivatives package
Yvan Masson's avatar
Yvan Masson committed
406
407
408
409
410
411
412
413
414
415
416
417

Below instructions are very simple: do not hesitate to read the dedicated
chapter of the excellent
[Debian Administrator's Handbook](https://debian-handbook.info/browse/stable/sect.building-first-package.html)
for a step-by-step initiation or the
[official Debian documentation](https://www.debian.org/doc/manuals/maint-guide)
for full details. Please also understand that I have no particular experience
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`:

Yvan Masson's avatar
Yvan Masson committed
418
```
Yvan Masson's avatar
Yvan Masson committed
419
420
421
# apt install build-essential dh_make devscripts
```

Yvan Masson's avatar
Yvan Masson committed
422
423
Go inside `~/my-remote-help-tool/` and generate all files needed for proper
packaging. Modify the following command to match:
Yvan Masson's avatar
Yvan Masson committed
424
425
426
427

- your name/company
- your package name (still "my-remote-help-tool" in our example)
- the "upstream" version number (for example "1.1" if RemoteHelpBuilder is in
Yvan Masson's avatar
Yvan Masson committed
428
  version 1 and if you publish it for the first time)
Yvan Masson's avatar
Yvan Masson committed
429
- your email address
Yvan Masson's avatar
Yvan Masson committed
430

Yvan Masson's avatar
Yvan Masson committed
431
```
Yvan Masson's avatar
Yvan Masson committed
432
cd ~/my-remote-help-tool/ && \
Yvan Masson's avatar
Yvan Masson committed
433
DEBFULLNAME="<your name>" dh_make \
Yvan Masson's avatar
Yvan Masson committed
434
  --packagename my-remote-help-tool_<upstream version> \
Yvan Masson's avatar
Yvan Masson committed
435
436
437
438
439
440
  --copyright gpl3 \
  --email <your email address> \
  --indep
  --createorig
```

Yvan Masson's avatar
Yvan Masson committed
441
442
Many files useless for this simple package have been created in the `debian/`
subdirectory, so we delete them:
Yvan Masson's avatar
Yvan Masson committed
443

Yvan Masson's avatar
Yvan Masson committed
444
```
Yvan Masson's avatar
Yvan Masson committed
445
446
447
448
449
$ 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
```

You now need to edit some of the remaining files:

Yvan Masson's avatar
Yvan Masson committed
450
451
452
453
- `changelog`: modify the changelog of the initial release
- `compat`: do not modify
- `control`:
  - edit homepage and description (each line of the long description must begin
Yvan Masson's avatar
Yvan Masson committed
454
    with a space)
Yvan Masson's avatar
Yvan Masson committed
455
456
  - replace line `Depends: ${misc:Depends}` by `Depends: openssh-client, sshpass, x11vnc, yad, gnome-icon-theme`
- `copyright`: add the source and copyright for all the files (normally you
Yvan Masson's avatar
Yvan Masson committed
457
458
  would have to give credits to this project: this is great if you do so, but
  currently I do not require it)
Yvan Masson's avatar
Yvan Masson committed
459
460
- `rules`: do not modify
- `source/format`: do not modify
Yvan Masson's avatar
Yvan Masson committed
461
462

Still in the new `debian/` subdirectory, create a file called
Yvan Masson's avatar
Yvan Masson committed
463
464
`my-remote-help-tool.install` that defines where all files must be installed to.
Do not forget to modify it:
Yvan Masson's avatar
Yvan Masson committed
465
466
467
468

```
my-remote-help-tool                         usr/bin/
my-remote-help-tool.desktop                 usr/share/applications/
Yvan Masson's avatar
Yvan Masson committed
469
variables                                   usr/share/my-remote-help-tool/
Yvan Masson's avatar
Yvan Masson committed
470
471
472
473
474
475
476
477
ssh-server-public-key                       usr/share/my-remote-help-tool/
icons/48x48/my-remote-help-tool.png         usr/share/icons/hicolor/48x48/apps/
icons/128x128/my-remote-help-tool.png       usr/share/icons/hicolor/128x128/apps/
icons/256x256/my-remote-help-tool.png       usr/share/icons/hicolor/256x256/apps/
icons/512x512/my-remote-help-tool.png       usr/share/icons/hicolor/512x512/apps/
icons/scalable/my-remote-help-tool.svgz     usr/share/icons/hicolor/scalable/apps/
```

Yvan Masson's avatar
Yvan Masson committed
478
Finaly, go back to `~/my-remote-help-tool/` and build the package:
Yvan Masson's avatar
Yvan Masson committed
479

Yvan Masson's avatar
Yvan Masson committed
480
```
Yvan Masson's avatar
Yvan Masson committed
481
482
483
$ dpkg-buildpackage --unsigned-source --unsigned-changes
```

Yvan Masson's avatar
Yvan Masson committed
484
485
486
Resulting package and associated files (useless for us) are created in the
parent directory. Just test it and you are now ready to help Debian and
derivatives users!
Yvan Masson's avatar
Yvan Masson committed
487

Yvan Masson's avatar
Yvan Masson committed
488
489
Note: If your icon does not appear when running the client, see
(this entry)[#icon-is-not-displayed-when-running-the-linux-client] of the FAQ.
Yvan Masson's avatar
Yvan Masson committed
490
491


Yvan Masson's avatar
Yvan Masson committed
492
## Updating the Debian and derivatives package
Yvan Masson's avatar
Yvan Masson committed
493

Yvan Masson's avatar
Yvan Masson committed
494
### When you need to fix packaging
Yvan Masson's avatar
Yvan Masson committed
495

Yvan Masson's avatar
Yvan Masson committed
496
497
498
499
If you change any file in `~/my-remote-help-tool/debian` you need to rebuild the
package. `cd` into `~/my-remote-help-tool/` and use the following command to
edit the changelog. Be careful to increment the Debian revision (the number
after the `-`), `1.1-2` in this example:
Yvan Masson's avatar
Yvan Masson committed
500

Yvan Masson's avatar
Yvan Masson committed
501
```
Yvan Masson's avatar
Yvan Masson committed
502
$ DEBFULLNAME=<your name> DEBEMAIL=<your email> debchange --newversion 1.1-2 --preserve
Yvan Masson's avatar
Yvan Masson committed
503
504
505
506
```

Finalize the changelog:

Yvan Masson's avatar
Yvan Masson committed
507
```
Yvan Masson's avatar
Yvan Masson committed
508
$ DEBFULLNAME=<your name> DEBEMAIL=<your email> debchange --release ""
Yvan Masson's avatar
Yvan Masson committed
509
510
511
512
```

And rebuild the package:

Yvan Masson's avatar
Yvan Masson committed
513
```
Yvan Masson's avatar
Yvan Masson committed
514
515
516
517
$ dpkg-buildpackage --unsigned-source --unsigned-changes
```


Yvan Masson's avatar
Yvan Masson committed
518
### For everything else
Yvan Masson's avatar
Yvan Masson committed
519
520
521
522
523

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
`my-remote-help-tool.desktop`), you will have to build a new package.

Yvan Masson's avatar
Yvan Masson committed
524
525
526
527
Make the changes in `~/my-remote-help-tool/`. Do not forget to adapt
`~/my-remote-help-tool/debian/` files if needed.

Define what will be the new version number of your package:
Yvan Masson's avatar
Yvan Masson committed
528

Yvan Masson's avatar
Yvan Masson committed
529
530
531
532
533
- If you include some RemoteHelpBuilder changes, increase the first number,
- If you modify one of your files, increase the second number,
- In all cases, reset the Debian revision to `1`.

Edit the changelog, specifying the version (`1.2-1` in this example):
Yvan Masson's avatar
Yvan Masson committed
534

Yvan Masson's avatar
Yvan Masson committed
535
```
Yvan Masson's avatar
Yvan Masson committed
536
$ DEBFULLNAME=<your name> DEBEMAIL=<your email> debchange --newversion 1.2-1 --preserve
Yvan Masson's avatar
Yvan Masson committed
537
538
```

Yvan Masson's avatar
Yvan Masson committed
539
Finalize the changelog:
Yvan Masson's avatar
Yvan Masson committed
540

Yvan Masson's avatar
Yvan Masson committed
541
```
Yvan Masson's avatar
Yvan Masson committed
542
$ DEBFULLNAME=<your name> DEBEMAIL=<your email> debchange --release ""
Yvan Masson's avatar
Yvan Masson committed
543
544
```

Yvan Masson's avatar
Yvan Masson committed
545
546
547
Create a tarball to simulate the upstream release (otherwise dpkg-buildpackage
will not work), with a filename ending with `_<version>.orig.tar.gz` (note that
the version must not include the Debian revision):
Yvan Masson's avatar
Yvan Masson committed
548

Yvan Masson's avatar
Yvan Masson committed
549
```
Yvan Masson's avatar
Yvan Masson committed
550
$ tar -caf my-remote-help-tool_1.2.orig.tar.gz .
Yvan Masson's avatar
Yvan Masson committed
551
552
553
554
```

And rebuild the package:

Yvan Masson's avatar
Yvan Masson committed
555
```
Yvan Masson's avatar
Yvan Masson committed
556
557
558
559
$ dpkg-buildpackage --unsigned-source --unsigned-changes
```


Yvan Masson's avatar
Yvan Masson committed
560
# Windows client
Yvan Masson's avatar
Yvan Masson committed
561

Yvan Masson's avatar
Yvan Masson committed
562
## First build
Yvan Masson's avatar
Yvan Masson committed
563

Yvan Masson's avatar
Yvan Masson committed
564
### Prerequisites
Yvan Masson's avatar
Yvan Masson committed
565
566
567
568

This requires the use of a Windows computer.

Create a directory that will contain all your custom files in it. It is easier
Yvan Masson's avatar
Yvan Masson committed
569
570
571
to use your "computer friendly" software name chosen above, so in this
documentation we will use `my-remote-help-tool\`. It is advised that you create
it in a VCS to keep track of your changes.
Yvan Masson's avatar
Yvan Masson committed
572
573
574
575
576

Also, ensure you have access to files inside the `Windows-client` directory of
RemoteHelpBuilder.


Yvan Masson's avatar
Yvan Masson committed
577
### PuTTY
Yvan Masson's avatar
Yvan Masson committed
578
579
580
581
582
583

From the
[PuTTY website](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html),
download the 32 bits version of `plink.exe` and save it to
`my-remote-help-tool\Sources\PuTTY\`.

Yvan Masson's avatar
Yvan Masson committed
584
Download PuTTY Unix source archive and extract the `LICENCE` file to
Yvan Masson's avatar
Yvan Masson committed
585
586
587
588
589
590
`my-remote-help-tool\Sources\PuTTY\`.

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.


Yvan Masson's avatar
Yvan Masson committed
591
### UltraVNC
Yvan Masson's avatar
Yvan Masson committed
592
593

From the [UltraVNC website](http://www.uvnc.com), download the 32 bits version
Yvan Masson's avatar
Yvan Masson committed
594
and save it anywhere on a Windows computer. Run the installer, which should be
Yvan Masson's avatar
Yvan Masson committed
595
596
597
598
called something like `UltraVNC_1_2_24_X86_Setup.exe`. When choosing components
to install, you can choose only `UltraVNC Server`. Do not register the system
service.

Yvan Masson's avatar
Yvan Masson committed
599
600
601
602
From the installation target (probably `C:\Program Files (x86)\uvnc bvba\`),
copy `UltraVNC\` directory to `my-remote-help-tool\Sources\`. Then, replace the
settings file `my-remote-help-tool\Sources\UltraVNC\ultravnc.ini` by the one
provided in the `Windows-client\` directory of RemoteHelpBuilder.
Yvan Masson's avatar
Yvan Masson committed
603
604
605
606
607
608
609

Optionnal: If you want to generate yourself a proper `ultravnc.ini`:

- Run the newly installed `UltraVNC server settings` application.
- In the `Network` tab, uncheck `Enable Java port` and check `LoopbackOnly`.
- In the `Security` tab, define the two passwords (I could not make it work
  without password or with a blank password). The `ultravnc.ini` file provided
Yvan Masson's avatar
Yvan Masson committed
610
  by RemoteHelpBuilder has password sets to `foo`.
Yvan Masson's avatar
Yvan Masson committed
611
612
613
614
615
616
- Click `OK` to generate your `ultravnc.ini`

Notes:

- Some of the UltraVNC files are certainely not needed, but I do not know which
  ones.
Yvan Masson's avatar
Yvan Masson committed
617
- This step might be possible under Wine but running the installer is not
Yvan Masson's avatar
Yvan Masson committed
618
619
620
  straightforward.


Yvan Masson's avatar
Yvan Masson committed
621
### Wrapper script and variables
Yvan Masson's avatar
Yvan Masson committed
622
623
624
625
626

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:

Yvan Masson's avatar
Yvan Masson committed
627
```
Yvan Masson's avatar
Yvan Masson committed
628
plink.exe -v -batch -P <ssh port> <FQDN or IP address>
Yvan Masson's avatar
Yvan Masson committed
629
630
```

Yvan Masson's avatar
Yvan Masson committed
631
The variable that will be used is the line that looks like
Yvan Masson's avatar
Yvan Masson committed
632
633
634
635
636
637
`ssh-ed25519 255 e5:32:8f:c3:fb:c6:e3:6e:8a:45:78:dc:d8:5c:84:03`.

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:

Yvan Masson's avatar
Yvan Masson committed
638
```
Yvan Masson's avatar
Yvan Masson committed
639
$ printf "ssh-rsa "; ssh-keygen -l -E md5 -f ~/my-remote-help-tool/ssh-server-public-key | sed 's/MD5://' | cut -d " " -f -2
Yvan Masson's avatar
Yvan Masson committed
640
641
```

Yvan Masson's avatar
Yvan Masson committed
642
Copy `Windows-client\RemoteHelp.vbs` to `my-remote-help-tool\Sources\`. Edit the
Yvan Masson's avatar
Yvan Masson committed
643
644
645
646
647
648
variables at the beginning to suit your needs. For those who do not know
VBScript, see example values for quoting and line returns.

Also, do not hesitate to add your copyright at the beginning of the file.


Yvan Masson's avatar
Yvan Masson committed
649
### License and changelog
Yvan Masson's avatar
Yvan Masson committed
650

Yvan Masson's avatar
Yvan Masson committed
651
Copy `Windows-client\License.txt` and `Windows-client\Changelog.txt` to
Yvan Masson's avatar
Yvan Masson committed
652
653
`my-remote-help-tool\Sources\`.

Yvan Masson's avatar
Yvan Masson committed
654
655
656
Modify them to have a proper changelog and eventually to add your copyright in
the license file.

Yvan Masson's avatar
Yvan Masson committed
657

Yvan Masson's avatar
Yvan Masson committed
658
### Software icon
Yvan Masson's avatar
Yvan Masson committed
659
660
661

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
Yvan Masson's avatar
Yvan Masson committed
662
I use GIMP to export my logo in 256x256 px in the .ico format. Save it in
Yvan Masson's avatar
Yvan Masson committed
663
664
665
`my-remote-help-tool\Sources\`.


Yvan Masson's avatar
Yvan Masson committed
666
### Building with InnoSetup
Yvan Masson's avatar
Yvan Masson committed
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681

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
run it on Windows, but it also works well under Wine (tested with version 4.0).
Here we use installer `innosetup-qsp-5.6.1-unicode.exe` but I suppose it should
work with any other version. Let Inno Setup installer install also the "Inno
Setup Preprocessor".

Copy `Windows-client\InnoSetup.iss` to `my-remote-help-tool\`, and modify it
with InnoSetup to suit your needs:

- Generate a new application GUID by going in "Tools -> Generate GUID".
- Modify variables in the `[Setup]` section.
- Eventually add or removes languages in the `[Languages]` section.

Yvan Masson's avatar
Yvan Masson committed
682
683
684
685
686
687
Note that all encodings are not supported: for example, on my setup, I must use
ISO-8859-15 (Windows-1252) and not UTF-8.

Once done, click on the "Compile" button at the top of the window and your
installer will appear in `my-remote-help-tool\Output\`. Test the installer
(works well under Wine) and your program (which obviously needs Windows).
Yvan Masson's avatar
Yvan Masson committed
688
689


Yvan Masson's avatar
Yvan Masson committed
690
## Building a new client version
Yvan Masson's avatar
Yvan Masson committed
691
692
693
694
695
696
697
698
699
700
701

When a new version of RemoteHelpBuilder improves the VBScript (fortunately it
will happen!), when PuTTY or UltraVNC release a security update, or when you
want to improve the InnoSetup installer, you need to build a new client version.

- Update files that need it in `my-remote-help-tool\Sources\`.
- Explain what changes in `Windows-client\Changelog.txt`.
- Edit `my-remote-help-tool\InnoSetup.iss` to eventually increase `AppVersion`
- Compile the installer with InnoSetup.


Yvan Masson's avatar
Yvan Masson committed
702
# Usage
Yvan Masson's avatar
Yvan Masson committed
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718

Finally the easy part!

1. First time you help someone, explain to the helped how to install your client
   software.
2. Connect to the intermediate server with X forwarding and eventually
   compression (`-C`, if connection from the intermediate server to your
   computer is too slow): `ssh -XC <username>@<intermediate_server> -p <ssh_port>`
3. Generate a random password: `sudo remote-help-toggle enable`
4. Give this password to the helped so that he can type it in the client
   software.
5. Start the VNC client (command line was written when running the previous
   command), and provide help!
3. When done, disable the remote-help user: `sudo remote-help-toggle disable`


Yvan Masson's avatar
Yvan Masson committed
719
# Release policy
Yvan Masson's avatar
Yvan Masson committed
720

Yvan Masson's avatar
Yvan Masson committed
721
722
723
724
A new RemoteHelpBuilder release is published when commits modify one of the
provided files of Windows or Linux client (except when modification is only on
examples, comments or formatting). No release is published when documentation is
modified.
Yvan Masson's avatar
Yvan Masson committed
725

Yvan Masson's avatar
Yvan Masson committed
726

Yvan Masson's avatar
Yvan Masson committed
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
# Frequently asked questions

## Icon is not displayed when running the Linux client

If your home directory contains a directory with the exact same name of
your icon, your icon will not appear where running the client software: this is
because the prompt is done with Yad, which uses GTK, which tries to use the
folder as the icon.


## How to run the VNC client on your computer and not on the server

By default, OpenSSH server does not expose on the network the ports forwarded by
clients. This is very good thing! If you want to be able to run the VNC client
on your computer and not on the server, you need to add the following line in
`/etc/ssh/sshd_config`:

```
Match User remote-help

    GatewayPorts yes

```

Warning: As there is no VNC password, be very careful to properly restrict
access to TCP port 5900 on your server. If you do not know how to do this, do
not use this setting!


# License
Yvan Masson's avatar
Yvan Masson committed
757

Yvan Masson's avatar
Yvan Masson committed
758
Copyright (C) 2019 Yvan Masson, https://masson-informatique.fr,
Yvan Masson's avatar
Yvan Masson committed
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
yvan@masson-informatique.fr

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.