/mandos/trunk : revision 49

1

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

2

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

3

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

4

<!ENTITY VERSION "1.0">

5

<!ENTITY COMMANDNAME "mandos">

6

<!ENTITY OVERVIEW SYSTEM "overview.xml">

7

]>

8

9

10

11

<title>&COMMANDNAME;</title>

12

13

<productname>&COMMANDNAME;</productname>

14

<productnumber>&VERSION;</productnumber>

15

16

17

<firstname>Björn</firstname>

18

<surname>Påhlsson</surname>

19

20

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

21

</address>

22

</author>

23

24

<firstname>Teddy</firstname>

25

<surname>Hogeborn</surname>

26

27

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

28

</address>

29

</author>

30

</authorgroup>

31

32

33

<holder>Teddy Hogeborn</holder>

34

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

35

</copyright>

36

37

<para>

38

This manual page is free software: you can redistribute it

39

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

40

License as published by the Free Software Foundation,

41

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

42

later version.

43

</para>

44

45

<para>

46

This manual page is distributed in the hope that it will

47

be useful, but WITHOUT ANY WARRANTY; without even the

48

implied warranty of MERCHANTABILITY or FITNESS FOR A

49

PARTICULAR PURPOSE. See the GNU General Public License

50

for more details.

51

</para>

52

53

<para>

54

You should have received a copy of the GNU General Public

55

License along with this program; If not, see

56

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

57

</para>

58

</legalnotice>

59

</refentryinfo>

60

61

62

<refentrytitle>&COMMANDNAME;</refentrytitle>

63

64

</refmeta>

65

66

67

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

68

69

Sends encrypted passwords to authenticated Mandos clients

70

</refpurpose>

71

</refnamediv>

72

73

74

75

<command>&COMMANDNAME;</command>

76

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

77

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

78

79

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

80

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

81

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

82

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

83

</cmdsynopsis>

84

85

<command>&COMMANDNAME;</command>

86

87

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

88

89

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

90

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

91

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

92

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

93

</cmdsynopsis>

94

95

<command>&COMMANDNAME;</command>

96

97

</cmdsynopsis>

98

99

<command>&COMMANDNAME;</command>

100

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

101

</cmdsynopsis>

102

103

<command>&COMMANDNAME;</command>

104

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

105

</cmdsynopsis>

106

</refsynopsisdiv>

107

108

109

<title>DESCRIPTION</title>

110

<para>

111

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

112

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

113

client host computers. The Mandos server uses Zeroconf to

114

announce itself on the local network, and uses TLS to

115

communicate securely with and to authenticate the clients. The

116

Mandos server uses IPv6 to allow Mandos clients to use IPv6

117

link-local addresses, since the clients will probably not have

118

any other addresses configured (see <xref linkend="overview"/>).

119

Any authenticated client is then given the stored pre-encrypted

120

password 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 client host computer with an

131

<emphasis>encrypted root file system</emphasis>. See <xref

132

linkend="overview"/> for details.

133

</para>

134

135

</refsect1>

136

137

138

<title>OPTIONS</title>

139

140

141

142

143

144

<para>

145

Show a help message and exit

146

</para>

147

</listitem>

148

</varlistentry>

149

150

151

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

152

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

153

154

<para>

155

Only announce the server and listen to requests on network

156

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

157

use all available interfaces.

158

</para>

159

</listitem>

160

</varlistentry>

161

162

163

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

164

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

165

166

<para>

167

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

168

specific address. This must currently be an IPv6 address;

169

an IPv4 address can be specified using the

170

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

171

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

172

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

173

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

174

all available addresses.

175

</para>

176

</listitem>

177

</varlistentry>

178

179

180

181

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

182

183

<para>

184

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

185

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

186

port given by the operating system.

187

</para>

188

</listitem>

189

</varlistentry>

190

191

192

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

193

194

<para>

195

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

196

tests, etc.

197

</para>

198

</listitem>

199

</varlistentry>

200

201

202

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

203

204

<para>

205

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

206

foreground and print a lot of debugging information. The

207

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

208

</para>

209

</listitem>

210

</varlistentry>

211

212

213

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

214

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

215

216

<para>

217

GnuTLS priority string for the TLS handshake with the

218

clients. The default is

219

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

220

See <citerefentry><refentrytitle>gnutls_priority_init

221

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

222

for the syntax. <emphasis>Warning</emphasis>: changing

223

this may make the TLS handshake fail, making communication

224

with clients impossible.

225

</para>

226

</listitem>

227

</varlistentry>

228

229

230

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

231

</literal></term>

232

233

<para>

234

Zeroconf service name. The default is

235

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

236

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

237

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

238

which would not normally be useful. If there are name

239

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

240

newer server will automatically rename itself to

241

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

242

therefore, this option is not needed in that case.

243

</para>

244

</listitem>

245

</varlistentry>

246

247

248

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

249

</literal></term>

250

251

<para>

252

Directory to search for configuration files. Default is

253

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

254

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

255

256

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

257

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

258

</para>

259

</listitem>

260

</varlistentry>

261

262

263

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

264

265

<para>

266

Prints the program version and exit.

267

</para>

268

</listitem>

269

</varlistentry>

270

</variablelist>

271

</refsect1>

272

273

274

<title>OVERVIEW</title>

275

&OVERVIEW;

276

<para>

277

This program is the server part. It is a normal server program

278

and will run in a normal system environment, not in an initial

279

RAM disk environment.

280

</para>

281

</refsect1>

282

283

284

<title>NETWORK PROTOCOL</title>

285

<para>

286

The Mandos server announces itself as a Zeroconf service of type

287

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

288

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

289

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

290

protocol version, which currently is

291

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

292

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

293

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

294

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

295

The Mandos client must supply an OpenPGP certificate, and the

296

fingerprint of this certificate is used by the Mandos server to

297

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

298

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

299

authentication or authorization is done by the server.

300

</para>

301

<table>

302

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

303

<row>

304

<entry>Mandos Client</entry>

305

<entry>Direction</entry>

306

<entry>Mandos Server</entry>

307

</row>

308

</thead><tbody>

309

<row>

310

<entry>Connect</entry>

311

312

</row>

313

<row>

314

315

316

</row>

317

<row>

318

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

319

</emphasis></entry>

320

321

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

322

</emphasis></entry>

323

</row>

324

<row>

325

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

326

327

</row>

328

<row>

329

330

331

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

332

</row>

333

<row>

334

335

336

<entry>Close</entry>

337

</row>

338

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

339

</refsect1>

340

341

342

<title>CHECKING</title>

343

<para>

344

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

345

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

346

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

347

longer eligible to receive the encrypted password. The timeout,

348

checker program, and interval between checks can be configured

349

both globally and per client; see <citerefentry>

350

<refentrytitle>mandos.conf</refentrytitle>

351

352

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

353

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

354

</para>

355

</refsect1>

356

357

358

<title>LOGGING</title>

359

<para>

360

The server will send log messaged with various severity levels

361

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

362

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

363

and also show them on the console.

364

</para>

365

</refsect1>

366

367

368

<title>EXIT STATUS</title>

369

<para>

370

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

371

critical error is encountered.

372

</para>

373

</refsect1>

374

375

376

<title>FILES</title>

377

<para>

378

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

379

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

380

files. The default file names are listed here.

381

</para>

382

383

384

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

385

386

<para>

387

Server-global settings. See

388

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

389

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

390

</para>

391

</listitem>

392

</varlistentry>

393

394

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

395

396

<para>

397

List of clients and client-specific settings. See

398

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

399

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

400

</para>

401

</listitem>

402

</varlistentry>

403

404

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

405

406

<para>

407

The file containing the process id of

408

<command>&COMMANDNAME;</command>.

409

</para>

410

</listitem>

411

</varlistentry>

412

413

414

415

<para>

416

The Unix domain socket to where local syslog messages are

417

sent.

418

</para>

419

</listitem>

420

</varlistentry>

421

</variablelist>

422

</refsect1>

423

424

425

426

<para>

427

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

428

backtrace. This could be considered a feature.

429

</para>

430

</refsect1>

431

432

433

<title>EXAMPLES</title>

434

435

<para>

436

Normal invocation needs no options:

437

</para>

438

<para>

439

<userinput>mandos</userinput>

440

</para>

441

</informalexample>

442

443

<para>

444

Run the server in debug mode, read configuration files from

445

the <filename>~/mandos</filename> directory, and use the

446

Zeroconf service name <quote>Test</quote> to not collide with

447

any other official Mandos server on this host:

448

</para>

449

<para>

450

451

452

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

453

454

</para>

455

</informalexample>

456

457

<para>

458

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

459

only on the link-local address on that interface:

460

</para>

461

<para>

462

463

464

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

465

466

</para>

467

</informalexample>

468

</refsect1>

469

470

471

<title>SECURITY</title>

472

473

<title>SERVER</title>

474

<para>

475

Running this &COMMANDNAME; server program should not in itself

476

present any security risk to the host computer running it.

477

The program does not need any special privileges to run, and

478

is designed to run as a non-root user.

479

</para>

480

</refsect2>

481

482

<title>CLIENTS</title>

483

<para>

484

The server only gives out its stored data to clients which

485

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

486

guaranteed by the fact that the client sends its OpenPGP

487

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

488

genuine. The server computes the fingerprint of the key

489

itself and looks up the fingerprint in its list of

490

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

491

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

492

<manvolnum>5</manvolnum></citerefentry>)

493

<emphasis>must</emphasis> be made non-readable by anyone

494

except the user running the server.

495

</para>

496

<para>

497

As detailed in <xref linkend="checking"/>, the status of all

498

client computers will continually be checked and be assumed

499

compromised if they are gone for too long.

500

</para>

501

<para>

502

For more details on client-side security, see

503

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

504

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

505

</para>

506

</refsect2>

507

</refsect1>

508

509

510

511

512

513

<term>

514

515

<refentrytitle>password-request</refentrytitle>

516

<manvolnum>8mandos</manvolnum>

517

</citerefentry>

518

</term>

519

520

<para>

521

This is the actual program which talks to this server.

522

Note that it is normally not invoked directly, and is only

523

run in the initial RAM disk environment, and not on a

524

fully started system.

525

</para>

526

</listitem>

527

</varlistentry>

528

529

<term>

530

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

531

</term>

532

533

<para>

534

Zeroconf is the network protocol standard used by clients

535

for finding this Mandos server on the local network.

536

</para>

537

</listitem>

538

</varlistentry>

539

540

<term>

541

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

542

</term>

543

544

<para>

545

Avahi is the library this server calls to implement

546

Zeroconf service announcements.

547

</para>

548

</listitem>

549

</varlistentry>

550

551

<term>

552

<ulink

553

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

554

</term>

555

556

<para>

557

GnuTLS is the library this server uses to implement TLS for

558

communicating securely with the client, and at the same time

559

confidently get the client’s public OpenPGP key.

560

</para>

561

</listitem>

562

</varlistentry>

563

564

<term>

565

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

566

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

567

Unicast Addresses</citation>

568

</term>

569

570

<para>

571

The clients use IPv6 link-local addresses, which are

572

immediately usable since a link-local addresses is

573

automatically assigned to a network interfaces when it is

574

brought up.

575

</para>

576

</listitem>

577

</varlistentry>

578

579

<term>

580

<citation>RFC 4346: <citetitle>The Transport Layer Security

581

(TLS) Protocol Version 1.1</citetitle></citation>

582

</term>

583

584

<para>

585

TLS 1.1 is the protocol implemented by GnuTLS.

586

</para>

587

</listitem>

588

</varlistentry>

589

590

<term>

591

<citation>RFC 4880: <citetitle>OpenPGP Message

592

Format</citetitle></citation>

593

</term>

594

595

<para>

596

The data sent to clients is binary encrypted OpenPGP data.

597

</para>

598

</listitem>

599

</varlistentry>

600

601

<term>

602

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

603

Transport Layer Security</citetitle></citation>

604

</term>

605

606

<para>

607

This is implemented by GnuTLS and used by this server so

608

that OpenPGP keys can be used.

609

</para>

610

</listitem>

611

</varlistentry>

612

</variablelist>

613

</refsect1>

614

</refentry>