annotate INSTALL @ 1861:2b3a8026a6ce

Add re-exec for server This allows ASLR to re-randomize the address space for every connection, preventing some vulnerabilities from being exploitable by repeated probing. Overhead (memory and time) is yet to be confirmed. At present this is only enabled on Linux. Other BSD platforms with fexecve() would probably also work though have not been tested.
author Matt Johnston <matt@ucc.asn.au>
date Sun, 30 Jan 2022 10:14:56 +0800
parents f78e67527731
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
1 Basic Dropbear build instructions:
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
2
1493
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
3 - Edit localoptions.h to set which features you want. Available options
1524
d35cf9a5e0b5 rename default_options.h.in in docs too
Matt Johnston <matt@ucc.asn.au>
parents: 1493
diff changeset
4 are described in default_options.h, these will be overridden by
1493
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
5 anything set in localoptions.h
1565
2fd52c383163 mention localoptions.h being build directory, fix underscore in CHANGES
Matt Johnston <matt@ucc.asn.au>
parents: 1524
diff changeset
6 localoptions.h should be located in the build directory if you are
2fd52c383163 mention localoptions.h being build directory, fix underscore in CHANGES
Matt Johnston <matt@ucc.asn.au>
parents: 1524
diff changeset
7 building out of tree.
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
8
1493
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
9 - Configure for your system:
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
10 ./configure (optionally with --disable-zlib or --disable-syslog,
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
11 or --help for other options)
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
12
1814
f78e67527731 Add configure script to version control. Set timezone for release tarball
Matt Johnston <matt@ucc.asn.au>
parents: 1792
diff changeset
13 (you'll need to first run "autoconf; autoheader" if you edit configure.ac)
f78e67527731 Add configure script to version control. Set timezone for release tarball
Matt Johnston <matt@ucc.asn.au>
parents: 1792
diff changeset
14
1493
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
15 - Compile:
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
16
1493
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
17 make PROGRAMS="dropbear dbclient dropbearkey dropbearconvert scp"
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
18
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
19 - Optionally install, or copy the binaries another way
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
20
1493
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
21 make install (/usr/local/bin is usual default):
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
22
1493
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
23 or
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
24
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
25 make PROGRAMS="dropbear dbclient dropbearkey dropbearconvert scp" install
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
26
72
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
27 (you can leave items out of the PROGRAMS list to avoid compiling them. If you
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
28 recompile after changing the PROGRAMS list, you *MUST* "make clean" before
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
29 recompiling - bad things will happen otherwise)
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
30
1717
295377ecbf49 Add DEVELOPING.md
Matt Johnston <matt@ucc.asn.au>
parents: 1667
diff changeset
31 DEVELOPING.md has some notes on other developer topics, including debugging.
295377ecbf49 Add DEVELOPING.md
Matt Johnston <matt@ucc.asn.au>
parents: 1667
diff changeset
32
72
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
33 See MULTI for instructions on making all-in-one binaries.
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
34
1447
8f88f4290b22 document --enable-static in place of STATIC=1
Matt Johnston <matt@ucc.asn.au>
parents: 443
diff changeset
35 If you want to compile statically use ./configure --enable-static
8f88f4290b22 document --enable-static in place of STATIC=1
Matt Johnston <matt@ucc.asn.au>
parents: 443
diff changeset
36
8f88f4290b22 document --enable-static in place of STATIC=1
Matt Johnston <matt@ucc.asn.au>
parents: 443
diff changeset
37 By default Dropbear adds various build flags that improve robustness
1493
72fd994fe7bd Update build instructions for localoptions, and tidy
Matt Johnston <matt@ucc.asn.au>
parents: 1447
diff changeset
38 against programming bugs (good for security). If these cause problems
1447
8f88f4290b22 document --enable-static in place of STATIC=1
Matt Johnston <matt@ucc.asn.au>
parents: 443
diff changeset
39 they can be disabled with ./configure --disable-harden
72
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
40
443
2d943453cecf Fix spelling typo
Matt Johnston <matt@ucc.asn.au>
parents: 245
diff changeset
41 Binaries can be stripped with "make strip"
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
42
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
43 ============================================================================
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
44
245
b24730e11c83 add note about compiling for 386
Matt Johnston <matt@ucc.asn.au>
parents: 72
diff changeset
45 If you're compiling for a 386-class CPU, you will probably need to add
b24730e11c83 add note about compiling for 386
Matt Johnston <matt@ucc.asn.au>
parents: 72
diff changeset
46 CFLAGS=-DLTC_NO_BSWAP so that libtomcrypt doesn't use 486+ instructions.
b24730e11c83 add note about compiling for 386
Matt Johnston <matt@ucc.asn.au>
parents: 72
diff changeset
47
b24730e11c83 add note about compiling for 386
Matt Johnston <matt@ucc.asn.au>
parents: 72
diff changeset
48 ============================================================================
b24730e11c83 add note about compiling for 386
Matt Johnston <matt@ucc.asn.au>
parents: 72
diff changeset
49
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
50 Compiling with uClibc:
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
51
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
52 Firstly, make sure you have at least uclibc 0.9.17, as getusershell() in prior
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
53 versions is broken. Also note that you may get strange issues if your uClibc
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
54 headers don't match the library you are running with, ie the headers might
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
55 say that shadow password support exists, but the libraries don't have it.
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
56
72
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
57 Compiling for uClibc should be the same as normal, just set CC to the magic
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
58 uClibc toolchain compiler (ie export CC=i386-uclibc-gcc or whatever).
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
59 You can use "make STATIC=1" to make statically linked binaries, and it is
9597c2e3b9d4 Some doc changes
Matt Johnston <matt@ucc.asn.au>
parents: 69
diff changeset
60 advisable to strip the binaries too. If you're looking to make a small binary,
1667
986126448688 Update remaining advise to edit options.h
Alexander Dahl <ada@thorsis.com>
parents: 1565
diff changeset
61 you should remove unneeded ciphers and MD5, by editing localoptions.h
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
62
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
63 It is possible to compile zlib in, by copying zlib.h and zconf.h into a
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
64 subdirectory (ie zlibincludes), and
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
65
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
66 export CFLAGS="-Izlibincludes -I../zlibincludes"
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
67 export LDFLAGS=/usr/lib/libz.a
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
68
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
69 before ./configure and make.
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
70
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
71 If you disable zlib, you must explicitly disable compression for the client -
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
72 OpenSSH is possibly buggy in this regard, it seems you need to disable it
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
73 globally in ~/.ssh/config, not just in the host entry in that file.
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
74
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
75 You may want to manually disable lastlog recording when using uClibc, configure
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
76 with --disable-lastlog.
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
77
69
59d16db56e9f Simple text changes
Matt Johnston <matt@ucc.asn.au>
parents: 4
diff changeset
78 One common problem is pty allocation. There are a number of types of pty
59d16db56e9f Simple text changes
Matt Johnston <matt@ucc.asn.au>
parents: 4
diff changeset
79 allocation which can be used -- if they work properly, the end result is the
59d16db56e9f Simple text changes
Matt Johnston <matt@ucc.asn.au>
parents: 4
diff changeset
80 same for each type. Running configure should detect the best type to use
59d16db56e9f Simple text changes
Matt Johnston <matt@ucc.asn.au>
parents: 4
diff changeset
81 automatically, however for some systems, this may be incorrect. Some
59d16db56e9f Simple text changes
Matt Johnston <matt@ucc.asn.au>
parents: 4
diff changeset
82 things to note:
4
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
83
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
84 If your system expects /dev/pts to be mounted (this is a uClibc option),
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
85 make sure that it is.
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
86
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
87 Make sure that your libc headers match the library version you are using.
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
88
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
89 If openpty() is being used (HAVE_OPENPTY defined in config.h) and it fails,
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
90 you can try compiling with --disable-openpty. You will probably then need
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
91 to create all the /dev/pty?? and /dev/tty?? devices, which can be
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
92 problematic for devfs. In general, openpty() is the best way to allocate
fe6bca95afa7 Makefile.in contains updated files required
Matt Johnston <matt@ucc.asn.au>
parents:
diff changeset
93 PTYs, so it's best to try and get it working.