/mandos/trunk : revision 24.1.20

1

<?xml version='1.0' encoding='UTF-8'?>

2

<?xml-stylesheet type="text/xsl"

3

href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>

4

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

5

"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

6

<!ENTITY VERSION "1.0">

7

<!ENTITY COMMANDNAME "mandos">

8

]>

9

10

11

12

<title>&COMMANDNAME;</title>

13

14

<productname>&COMMANDNAME;</productname>

15

<productnumber>&VERSION;</productnumber>

16

17

18

<firstname>Björn</firstname>

19

<surname>Påhlsson</surname>

20

21

<email>belorn@fukt.bsnet.se</email>

22

</address>

23

</author>

24

25

<firstname>Teddy</firstname>

26

<surname>Hogeborn</surname>

27

28

<email>teddy@fukt.bsnet.se</email>

29

</address>

30

</author>

31

</authorgroup>

32

33

34

<holder>Teddy Hogeborn</holder>

35

<holder>Björn Påhlsson</holder>

36

</copyright>

37

38

<para>

39

This manual page is free software: you can redistribute it

40

and/or modify it under the terms of the GNU General Public

41

License as published by the Free Software Foundation,

42

either version 3 of the License, or (at your option) any

43

later version.

44

</para>

45

46

<para>

47

This manual page is distributed in the hope that it will

48

be useful, but WITHOUT ANY WARRANTY; without even the

49

implied warranty of MERCHANTABILITY or FITNESS FOR A

50

PARTICULAR PURPOSE. See the GNU General Public License

51

for more details.

52

</para>

53

54

<para>

55

You should have received a copy of the GNU General Public

56

License along with this program; If not, see

57

<ulink url="http://www.gnu.org/licenses/"/>.

58

</para>

59

</legalnotice>

60

</refentryinfo>

61

62

63

<refentrytitle>&COMMANDNAME;</refentrytitle>

64

65

</refmeta>

66

67

68

<refname><command>&COMMANDNAME;</command></refname>

69

70

Sends encrypted passwords to authenticated Mandos clients

71

</refpurpose>

72

</refnamediv>

73

74

75

76

<command>&COMMANDNAME;</command>

77

<arg choice='opt'>--interface<arg choice='plain'>IF</arg></arg>

78

<arg choice='opt'>--address<arg choice='plain'>ADDRESS</arg></arg>

79

80

<arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>

81

<arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>

82

<arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>

83

<arg choice='opt'>--debug</arg>

84

</cmdsynopsis>

85

86

<command>&COMMANDNAME;</command>

87

88

<arg choice='opt'>-a<arg choice='plain'>ADDRESS</arg></arg>

89

90

<arg choice='opt'>--priority<arg choice='plain'>PRIORITY</arg></arg>

91

<arg choice='opt'>--servicename<arg choice='plain'>NAME</arg></arg>

92

<arg choice='opt'>--configdir<arg choice='plain'>DIRECTORY</arg></arg>

93

<arg choice='opt'>--debug</arg>

94

</cmdsynopsis>

95

96

<command>&COMMANDNAME;</command>

97

98

</cmdsynopsis>

99

100

<command>&COMMANDNAME;</command>

101

<arg choice='plain'>--version</arg>

102

</cmdsynopsis>

103

104

<command>&COMMANDNAME;</command>

105

<arg choice='plain'>--check</arg>

106

</cmdsynopsis>

107

</refsynopsisdiv>

108

109

110

<title>DESCRIPTION</title>

111

<para>

112

<command>&COMMANDNAME;</command> is a server daemon which

113

handles incoming request for passwords for a pre-defined list of

114

client host computers. The Mandos server uses Zeroconf to

115

announce itself on the local network, and uses GnuTLS to

116

communicate securely with and to authenticate the clients.

117

Mandos uses IPv6 link-local addresses, since the clients are

118

assumed to not have any other addresses configured. Any

119

authenticated client is then given the pre-encrypted password

120

for that specific client.

121

</para>

122

123

</refsect1>

124

125

126

<title>PURPOSE</title>

127

128

<para>

129

The purpose of this is to enable <emphasis>remote and unattended

130

rebooting</emphasis> of any client host computer with an

131

<emphasis>encrypted root file system</emphasis>. The client

132

host computer should start a Mandos client in the initial RAM

133

disk environment, the Mandos client program communicates with

134

this server program to get an encrypted password, which is then

135

decrypted and used to unlock the encrypted root file system.

136

The client host computer can then continue its boot sequence

137

normally.

138

</para>

139

140

</refsect1>

141

142

143

<title>OPTIONS</title>

144

145

146

147

148

149

<para>

150

Show a help message and exit

151

</para>

152

</listitem>

153

</varlistentry>

154

155

156

<term><literal>-i</literal>, <literal>--interface <replaceable>

157

IF</replaceable></literal></term>

158

159

<para>

160

Only announce the server and listen to requests on network

161

interface <replaceable>IF</replaceable>. Default is to

162

use all available interfaces.

163

</para>

164

</listitem>

165

</varlistentry>

166

167

168

<term><literal>-a</literal>, <literal>--address <replaceable>

169

ADDRESS</replaceable></literal></term>

170

171

<para>

172

If this option is used, the server will only listen to a

173

specific address. This must currently be an IPv6 address;

174

an IPv4 address can be specified using the

175

<quote><literal>::FFFF:192.0.2.3</literal></quote> syntax.

176

Also, if a link-local address is specified, an interface

177

should be set, since a link-local address is only valid on

178

a single interface. By default, the server will listen to

179

all available addresses.

180

</para>

181

</listitem>

182

</varlistentry>

183

184

185

186

PORT</replaceable></literal></term>

187

188

<para>

189

If this option is used, the server to bind to that

190

port. By default, the server will listen to an arbitrary

191

port given by the operating system.

192

</para>

193

</listitem>

194

</varlistentry>

195

196

197

<term><literal>--check</literal></term>

198

199

<para>

200

Run the server's self-tests. This includes any unit

201

tests, etc.

202

</para>

203

</listitem>

204

</varlistentry>

205

206

207

<term><literal>--debug</literal></term>

208

209

<para>

210

If the server is run in debug mode, it will run in the

211

foreground and print a lot of debugging information. The

212

default is <emphasis>not</emphasis> to run in debug mode.

213

</para>

214

</listitem>

215

</varlistentry>

216

217

218

<term><literal>--priority <replaceable>

219

PRIORITY</replaceable></literal></term>

220

221

<para>

222

GnuTLS priority string for the TLS handshake with the

223

clients. See

224

<citerefentry><refentrytitle>gnutls_priority_init

225

</refentrytitle><manvolnum>3</manvolnum></citerefentry>

226

for the syntax. The default is

227

<quote><literal>SECURE256:!CTYPE-X.509:+CTYPE-OPENPGP</literal></quote>.

228

<emphasis>Warning</emphasis>: changing this may make the

229

TLS handshake fail, making communication with clients

230

impossible.

231

</para>

232

</listitem>

233

</varlistentry>

234

235

236

<term><literal>--servicename <replaceable>NAME</replaceable>

237

</literal></term>

238

239

<para>

240

Zeroconf service name. The default is

241

<quote><literal>Mandos</literal></quote>. You only need

242

to change this if you for some reason want to run more

243

than one server on the same <emphasis>host</emphasis>,

244

which would not normally be useful. If there are name

245

collisions on the same <emphasis>network</emphasis>, the

246

newer server will automatically rename itself to

247

<quote><literal>Mandos #2</literal></quote>, and so on,

248

therefore this option is not needed in that case.

249

</para>

250

</listitem>

251

</varlistentry>

252

253

254

<term><literal>--configdir <replaceable>DIR</replaceable>

255

</literal></term>

256

257

<para>

258

Directory to search for configuration files. Default is

259

<quote><literal>/etc/mandos</literal></quote>. See

260

<citerefentry><refentrytitle>mandos.conf</refentrytitle>

261

262

<refentrytitle>mandos-clients.conf</refentrytitle>

263

<manvolnum>5</manvolnum></citerefentry>.

264

</para>

265

</listitem>

266

</varlistentry>

267

268

269

<term><literal>--version</literal></term>

270

271

<para>

272

Prints the program version and exit.

273

</para>

274

</listitem>

275

</varlistentry>

276

</variablelist>

277

</refsect1>

278

279

280

<title>NETWORK PROTOCOL</title>

281

<para>

282

The Mandos server announces itself as a Zeroconf service of type

283

<quote><literal>_mandos._tcp</literal></quote>. The Mandos

284

client connects to the announced address and port, and sends a

285

line of text where the first whitespace-separated field is the

286

protocol version, which currently is

287

<quote><literal>1</literal></quote>. The client and server then

288

start a TLS protocol handshake with a slight quirk: the Mandos

289

server program acts as a TLS <quote>client</quote> while the

290

connecting Mandos client acts as a TLS <quote>server</quote>.

291

The Mandos client must supply an OpenPGP certificate, and the

292

fingerprint of this certificate is used by the Mandos server to

293

look up (in a list read from <filename>clients.conf</filename>

294

at start time) which binary blob to give the client. No other

295

authentication or authorization is done by the server.

296

</para>

297

<table>

298

<title>Mandos Protocol (Version 1)</title><tgroup cols="3"><thead>

299

<row>

300

<entry>Mandos Client</entry>

301

<entry>Direction</entry>

302

<entry>Mandos Server</entry>

303

</row>

304

</thead><tbody>

305

<row>

306

<entry>Connect</entry>

307

308

</row>

309

<row>

310

311

312

</row>

313

<row>

314

<entry>TLS handshake <emphasis>as TLS <quote>server</quote>

315

</emphasis></entry>

316

317

<entry>TLS handshake <emphasis>as TLS <quote>client</quote>

318

</emphasis></entry>

319

</row>

320

<row>

321

<entry>OpenPGP public key (part of TLS handshake)</entry>

322

323

</row>

324

<row>

325

326

327

<entry>Binary blob (client will assume OpenPGP data)</entry>

328

</row>

329

<row>

330

331

332

<entry>Close</entry>

333

</row>

334

</tbody></tgroup></table>

335

</refsect1>

336

337

338

<title>CHECKING</title>

339

<para>

340

The server will, by default, continually check that the clients

341

are still up. If a client has not been confirmed as being up

342

for some time, the client is assumed to be compromised and is no

343

longer eligible to receive the encrypted password. The timeout,

344

checker program and interval between checks can be configured

345

both globally and per client; see <citerefentry>

346

<refentrytitle>mandos.conf</refentrytitle>

347

348

<refentrytitle>mandos-clients.conf</refentrytitle>

349

<manvolnum>5</manvolnum></citerefentry>.

350

</para>

351

</refsect1>

352

353

354

<title>LOGGING</title>

355

<para>

356

The server will send log messaged with various severity levels

357

to <filename>/dev/log</filename>. With the

358

<option>--debug</option> option, it will log even more messages,

359

and also show them on the console.

360

</para>

361

</refsect1>

362

363

364

<title>EXIT STATUS</title>

365

<para>

366

The server will exit with a non-zero exit status only when a

367

critical error is encountered.

368

</para>

369

</refsect1>

370

371

372

<title>FILES</title>

373

<para>

374

Use the <option>--configdir</option> option to change where

375

<command>&COMMANDNAME;</command> looks for its configurations

376

files. The default file names are listed here.

377

</para>

378

379

380

<term><filename>/etc/mandos/mandos.conf</filename></term>

381

382

<para>

383

Server-global settings. See

384

<citerefentry><refentrytitle>mandos.conf</refentrytitle>

385

<manvolnum>5</manvolnum></citerefentry> for details.

386

</para>

387

</listitem>

388

</varlistentry>

389

390

<term><filename>/etc/mandos/clients.conf</filename></term>

391

392

<para>

393

List of clients and client-specific settings. See

394

<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>

395

<manvolnum>5</manvolnum></citerefentry> for details.

396

</para>

397

</listitem>

398

</varlistentry>

399

400

<term><filename>/var/run/mandos/mandos.pid</filename></term>

401

402

<para>

403

The file containing the process id of

404

<command>&COMMANDNAME;</command>.

405

</para>

406

</listitem>

407

</varlistentry>

408

409

410

411

<para>

412

The Unix domain socket to where local syslog messages are

413

sent.

414

</para>

415

</listitem>

416

</varlistentry>

417

</variablelist>

418

</refsect1>

419

420

421

422

<para>

423

This server might, on especially fatal errors, emit a Python

424

backtrace. This could be considered a feature.

425

</para>

426

</refsect1>

427

428

429

<title>EXAMPLES</title>

430

431

<para>

432

Normal invocation needs no options:

433

</para>

434

<para>

435

<userinput>mandos</userinput>

436

</para>

437

</informalexample>

438

439

<para>

440

Run the server in debug mode and read configuration files from

441

the <filename>~/mandos</filename> directory:

442

</para>

443

<para>

444

445

446

<userinput>mandos --debug --configdir ~/mandos --servicename Test</userinput>

447

448

</para>

449

</informalexample>

450

451

<para>

452

Run the server normally, but only listen to one interface and

453

only on the link-local address on that interface:

454

</para>

455

<para>

456

457

458

<userinput>mandos --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>

459

460

</para>

461

</informalexample>

462

</refsect1>

463

464

465

<title>SECURITY</title>

466

467

<title>SERVER</title>

468

<para>

469

Running the server should not in itself present any security

470

risk to the host computer running it.

471

</para>

472

</refsect2>

473

474

<title>CLIENTS</title>

475

<para>

476

The server only gives out its stored data to clients which

477

does have the OpenPGP key of the stored fingerprint. This is

478

guaranteed by the fact that the client sends its OpenPGP

479

public key in the TLS handshake; this ensures it to be

480

genuine. The server computes the fingerprint of the key

481

itself and looks up the fingerprint in its list of

482

clients. The <filename>clients.conf</filename> file (see

483

<citerefentry><refentrytitle>mandos-clients.conf</refentrytitle>

484

<manvolnum>5</manvolnum></citerefentry>) must be non-readable

485

by anyone except the user running the server.

486

</para>

487

<para>

488

For more details on client-side security, see

489

<citerefentry><refentrytitle>password-request</refentrytitle>

490

<manvolnum>8mandos</manvolnum></citerefentry>.

491

</para>

492

</refsect2>

493

</refsect1>

494

495

496

497

498

499

<citerefentry><refentrytitle>password-request</refentrytitle>

500

<manvolnum>8mandos</manvolnum></citerefentry>

501

</para></listitem>

502

503

504

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

505

<manvolnum>8mandos</manvolnum></citerefentry>

506

</para></listitem>

507

508

509

<ulink url="http://www.zeroconf.org/">Zeroconf</ulink>

510

</para></listitem>

511

512

513

<ulink url="http://www.avahi.org/">Avahi</ulink>

514

</para></listitem>

515

516

517

<ulink

518

url="http://www.gnu.org/software/gnutls/">GnuTLS</ulink>

519

</para></listitem>

520

521

522

<citation>RFC 4880: <citetitle>OpenPGP Message

523

Format</citetitle></citation>

524

</para></listitem>

525

526

527

<citation>RFC 5081: <citetitle>Using OpenPGP Keys for

528

Transport Layer Security</citetitle></citation>

529

</para></listitem>

530

531

532

<citation>RFC 4291: <citetitle>IP Version 6 Addressing

533

Architecture</citetitle>, section 2.5.6, Link-Local IPv6

534

Unicast Addresses</citation>

535

</para></listitem>

536

</itemizedlist>

537

</refsect1>

538

</refentry>