/mandos/trunk : revision 165

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">

6

<!ENTITY TIMESTAMP "2008-09-05">

7

]>

8

9

9

10

11

<title>&COMMANDNAME;</title>

11

<title>Mandos Manual</title>

12

13

<productname>&COMMANDNAME;</productname>

13

<productname>Mandos</productname>

14

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

15

16

16

17

17

18

<firstname>Björn</firstname>

33

34

<holder>Teddy Hogeborn</holder>

34

35

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

35

36

</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>

37

<xi:include href="legalnotice.xml"/>

59

38

</refentryinfo>

60

39

61

40

66

45

67

46

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

68

47

69

Sends encrypted passwords to authenticated Mandos clients

48

Gives encrypted passwords to authenticated Mandos clients

70

49

</refpurpose>

71

50

</refnamediv>

72

51

73

52

74

53

75

54

<command>&COMMANDNAME;</command>

76

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

77

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

78

79

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

80

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

81

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

82

<arg>--debug</arg>

83

</cmdsynopsis>

84

85

<command>&COMMANDNAME;</command>

86

87

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

88

89

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

90

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

91

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

92

<arg>--debug</arg>

55

<group>

56

<arg choice="plain"><option>--interface

57

58

<arg choice="plain"><option>-i

59

60

</group>

61

<sbr/>

62

<group>

63

<arg choice="plain"><option>--address

64

<replaceable>ADDRESS</replaceable></option></arg>

65

<arg choice="plain"><option>-a

66

<replaceable>ADDRESS</replaceable></option></arg>

67

</group>

68

<sbr/>

69

<group>

70

<arg choice="plain"><option>--port

71

72

<arg choice="plain"><option>-p

73

74

</group>

75

<sbr/>

76

<arg><option>--priority

77

<replaceable>PRIORITY</replaceable></option></arg>

78

<sbr/>

79

<arg><option>--servicename

80

81

<sbr/>

82

<arg><option>--configdir

83

<replaceable>DIRECTORY</replaceable></option></arg>

84

<sbr/>

85

<arg><option>--debug</option></arg>

93

86

</cmdsynopsis>

94

87

95

88

<command>&COMMANDNAME;</command>

96

89

97

98

90

91

99

92

</group>

100

93

</cmdsynopsis>

101

94

102

95

<command>&COMMANDNAME;</command>

103

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

96

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

104

97

</cmdsynopsis>

105

98

106

99

<command>&COMMANDNAME;</command>

107

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

100

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

108

101

</cmdsynopsis>

109

102

</refsynopsisdiv>

110

103

122

115

Any authenticated client is then given the stored pre-encrypted

123

116

password for that specific client.

124

117

</para>

125

126

118

</refsect1>

127

119

128

120

129

121

<title>PURPOSE</title>

130

131

122

<para>

132

123

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

133

124

rebooting</emphasis> of client host computer with an

134

125

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

135

126

linkend="overview"/> for details.

136

127

</para>

137

138

128

</refsect1>

139

129

140

130

141

131

<title>OPTIONS</title>

142

143

132

144

133

145

134

135

146

136

147

137

<para>

148

138

Show a help message and exit

149

139

</para>

150

140

</listitem>

151

141

</varlistentry>

152

153

154

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

155

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

156

157

<para>

158

Only announce the server and listen to requests on network

159

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

160

use all available interfaces. <emphasis>Note:</emphasis>

161

a failure to bind to the specified interface is not

162

considered critical, and the server does not exit.

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>

142

143

144

<term><option>--interface</option>

145

146

147

148

149

<xi:include href="mandos-options.xml" xpointer="interface"/>

150

</listitem>

151

</varlistentry>

152

153

154

<term><option>--address

155

<replaceable>ADDRESS</replaceable></option></term>

156

<term><option>-a

157

<replaceable>ADDRESS</replaceable></option></term>

158

159

<xi:include href="mandos-options.xml" xpointer="address"/>

160

</listitem>

161

</varlistentry>

162

163

164

<term><option>--port

165

166

<term><option>-p

167

168

169

<xi:include href="mandos-options.xml" xpointer="port"/>

170

</listitem>

171

</varlistentry>

172

173

174

<term><option>--check</option></term>

198

175

199

176

<para>

200

177

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

202

179

</para>

203

180

</listitem>

204

181

</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. The default is

224

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

225

See <citerefentry><refentrytitle>gnutls_priority_init

226

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

227

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

228

this may make the TLS handshake fail, making communication

229

with clients impossible.

230

</para>

231

</listitem>

232

</varlistentry>

233

234

235

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

236

</literal></term>

237

238

<para>

239

Zeroconf service name. The default is

240

<quote><literal>Mandos</literal></quote>. This only needs

241

to be changed this if it, for some reason, is necessary to

242

run more than one server on the same

243

<emphasis>host</emphasis>, which would not normally be

244

useful. If there are name collisions on the same

245

<emphasis>network</emphasis>, the newer server will

246

automatically rename itself to <quote><literal>Mandos

247

#2</literal></quote>, and so on; therefore, this option is

248

not needed in that case.

249

</para>

250

</listitem>

251

</varlistentry>

252

253

254

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

255

</literal></term>

182

183

184

<term><option>--debug</option></term>

185

186

<xi:include href="mandos-options.xml" xpointer="debug"/>

187

</listitem>

188

</varlistentry>

189

190

191

<term><option>--priority <replaceable>

192

PRIORITY</replaceable></option></term>

193

194

<xi:include href="mandos-options.xml" xpointer="priority"/>

195

</listitem>

196

</varlistentry>

197

198

199

<term><option>--servicename

200

201

202

<xi:include href="mandos-options.xml"

203

xpointer="servicename"/>

204

</listitem>

205

</varlistentry>

206

207

208

<term><option>--configdir

209

<replaceable>DIRECTORY</replaceable></option></term>

256

210

257

211

<para>

258

212

Directory to search for configuration files. Default is

266

220

</varlistentry>

267

221

268

222

269

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

223

<term><option>--version</option></term>

270

224

271

225

<para>

272

226

Prints the program version and exit.

278

232

279

233

280

234

<title>OVERVIEW</title>

281

&OVERVIEW;

235

<xi:include href="overview.xml"/>

282

236

<para>

283

237

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

284

238

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

285

RAM disk environment.

239

<acronym>RAM</acronym> disk environment.

286

240

</para>

287

241

</refsect1>

288

242

317

271

318

272

</row>

319

273

<row>

320

274

321

275

322

276

</row>

323

277

<row>

353

307

longer eligible to receive the encrypted password. The timeout,

354

308

checker program, and interval between checks can be configured

355

309

both globally and per client; see <citerefentry>

356

<refentrytitle>mandos.conf</refentrytitle>

357

358

310

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

359

311

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

360

312

</para>

363

315

364

316

<title>LOGGING</title>

365

317

<para>

366

The server will send log messaged with various severity levels

367

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

318

The server will send log message with various severity levels to

319

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

368

320

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

369

321

and also show them on the console.

370

322

</para>

382

334

<title>ENVIRONMENT</title>

383

335

384

336

385

337

386

338

387

339

<para>

388

340

To start the configured checker (see <xref

391

343

<varname>PATH</varname> to search for matching commands if

392

344

an absolute path is not given. See <citerefentry>

393

345

394

</citerefentry>

346

</citerefentry>.

395

347

</para>

396

348

</listitem>

397

349

</varlistentry>

427

379

</listitem>

428

380

</varlistentry>

429

381

430

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

382

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

431

383

432

384

<para>

433

385

The file containing the process id of

482

434

Debug mode is conflated with running in the foreground.

483

435

</para>

484

436

<para>

485

The console log messages does not show a timestamp.

437

The console log messages does not show a time stamp.

438

</para>

439

<para>

440

This server does not check the expire time of clients’ OpenPGP

441

keys.

486

442

</para>

487

443

</refsect1>

488

444

493

449

Normal invocation needs no options:

494

450

</para>

495

451

<para>

496

<userinput>mandos</userinput>

452

<userinput>&COMMANDNAME;</userinput>

497

453

</para>

498

454

</informalexample>

499

455

506

462

<para>

507

463

508

464

509

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

465

<userinput>&COMMANDNAME; --debug --configdir ~/mandos --servicename Test</userinput>

510

466

511

467

</para>

512

468

</informalexample>

518

474

<para>

519

475

520

476

521

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

477

<userinput>&COMMANDNAME; --interface eth7 --address fe80::aede:48ff:fe71:f6f2</userinput>

522

478

523

479

</para>

524

480

</informalexample>

531

487

<para>

532

488

Running this <command>&COMMANDNAME;</command> server program

533

489

should not in itself present any security risk to the host

534

computer running it. The program does not need any special

535

privileges to run, and is designed to run as a non-root user.

490

computer running it. The program switches to a non-root user

491

soon after startup.

536

492

</para>

537

493

</refsect2>

538

494

565

521

restarting servers if it is suspected that a client has, in

566

522

fact, been compromised by parties who may now be running a

567

523

fake Mandos client with the keys from the non-encrypted

568

initial RAM image of the client host. What should be done in

569

that case (if restarting the server program really is

570

necessary) is to stop the server program, edit the

524

initial <acronym>RAM</acronym> image of the client host. What

525

should be done in that case (if restarting the server program

526

really is necessary) is to stop the server program, edit the

571

527

configuration file to omit any suspect clients, and restart

572

528

the server program.

573

529

</para>

581

537

582

538

583

539

540

<para>

541

542

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

543

544

<refentrytitle>mandos.conf</refentrytitle>

545

546

<refentrytitle>password-request</refentrytitle>

547

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

548

549

</citerefentry>

550

</para>

584

551

585

552

586

553

<term>

587

588

<refentrytitle>password-request</refentrytitle>

589

<manvolnum>8mandos</manvolnum>

590

</citerefentry>

591

</term>

592

593

<para>

594

This is the actual program which talks to this server.

595

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

596

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

597

fully started system.

598

</para>

599

</listitem>

600

</varlistentry>

601

602

<term>

603

554

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

604

555

</term>

605

556

622

573

</varlistentry>

623

574

624

575

<term>

625

<ulink

626

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

576

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

577

>GnuTLS</ulink>

627

578

</term>

628

579

629

580

<para>

635

586

</varlistentry>

636

587

637

588

<term>

638

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

639

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

640

Unicast Addresses</citation>

589

RFC 4291: <citetitle>IP Version 6 Addressing

590

Architecture</citetitle>

641

591

</term>

642

592

643

<para>

644

The clients use IPv6 link-local addresses, which are

645

immediately usable since a link-local addresses is

646

automatically assigned to a network interfaces when it is

647

brought up.

648

</para>

593

594

595

<term>Section 2.2: <citetitle>Text Representation of

596

Addresses</citetitle></term>

597

598

</varlistentry>

599

600

<term>Section 2.5.5.2: <citetitle>IPv4-Mapped IPv6

601

Address</citetitle></term>

602

603

</varlistentry>

604

605

<term>Section 2.5.6, <citetitle>Link-Local IPv6 Unicast

606

Addresses</citetitle></term>

607

608

<para>

609

The clients use IPv6 link-local addresses, which are

610

immediately usable since a link-local addresses is

611

automatically assigned to a network interfaces when it

612

is brought up.

613

</para>

614

</listitem>

615

</varlistentry>

616

</variablelist>

649

617

</listitem>

650

618

</varlistentry>

651

619

652

620

<term>

653

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

654

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

621

RFC 4346: <citetitle>The Transport Layer Security (TLS)

622

Protocol Version 1.1</citetitle>

655

623

</term>

656

624

657

625

<para>

661

629

</varlistentry>

662

630

663

631

<term>

664

<citation>RFC 4880: <citetitle>OpenPGP Message

665

Format</citetitle></citation>

632

RFC 4880: <citetitle>OpenPGP Message Format</citetitle>

666

633

</term>

667

634

668

635

<para>

672

639

</varlistentry>

673

640

674

641

<term>

675

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

676

Transport Layer Security</citetitle></citation>

642

RFC 5081: <citetitle>Using OpenPGP Keys for Transport Layer

643

Security</citetitle>

677

644

</term>

678

645

679

646

<para>

685

652

</variablelist>

686

653

</refsect1>

687

654

</refentry>

655

656

657

658

659