/mandos/trunk : revision 89

3

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

4

<!ENTITY VERSION "1.0">

5

<!ENTITY COMMANDNAME "mandos">

6

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

6

<!ENTITY OVERVIEW SYSTEM "overview.xml">

7

]>

8

9

9

10

11

<title>Mandos Manual</title>

11

<title>&COMMANDNAME;</title>

12

13

<productname>Mandos</productname>

13

<productname>&COMMANDNAME;</productname>

14

<productnumber>&VERSION;</productnumber>

15

<date>&TIMESTAMP;</date>

16

15

17

16

18

17

<firstname>Björn</firstname>

34

33

<holder>Teddy Hogeborn</holder>

35

34

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

36

35

</copyright>

37

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

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>

38

59

</refentryinfo>

39

60

40

61

45

66

46

67

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

47

68

48

Gives encrypted passwords to authenticated Mandos clients

69

Sends encrypted passwords to authenticated Mandos clients

49

70

</refpurpose>

50

71

</refnamediv>

51

72

52

73

53

74

54

75

<command>&COMMANDNAME;</command>

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>

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>

86

93

</cmdsynopsis>

87

94

88

95

<command>&COMMANDNAME;</command>

89

96

90

91

97

98

92

99

</group>

93

100

</cmdsynopsis>

94

101

95

102

<command>&COMMANDNAME;</command>

96

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

103

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

97

104

</cmdsynopsis>

98

105

99

106

<command>&COMMANDNAME;</command>

100

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

107

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

101

108

</cmdsynopsis>

102

109

</refsynopsisdiv>

103

110

115

122

Any authenticated client is then given the stored pre-encrypted

116

123

password for that specific client.

117

124

</para>

125

118

126

</refsect1>

119

127

120

128

121

129

<title>PURPOSE</title>

130

122

131

<para>

123

132

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

124

133

rebooting</emphasis> of client host computer with an

125

134

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

126

135

linkend="overview"/> for details.

127

136

</para>

137

128

138

</refsect1>

129

139

130

140

131

141

<title>OPTIONS</title>

142

132

143

133

144

134

135

145

136

146

137

147

<para>

138

148

Show a help message and exit

139

149

</para>

140

150

</listitem>

141

151

</varlistentry>

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>

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>

175

198

176

199

<para>

177

200

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

179

202

</para>

180

203

</listitem>

181

204

</varlistentry>

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>

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>

210

256

211

257

<para>

212

258

Directory to search for configuration files. Default is

220

266

</varlistentry>

221

267

222

268

223

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

269

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

224

270

225

271

<para>

226

272

Prints the program version and exit.

232

278

233

279

234

280

<title>OVERVIEW</title>

235

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

281

&OVERVIEW;

236

282

<para>

237

283

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

238

284

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

239

<acronym>RAM</acronym> disk environment.

285

RAM disk environment.

240

286

</para>

241

287

</refsect1>

242

288

271

317

272

318

</row>

273

319

<row>

274

320

275

321

276

322

</row>

277

323

<row>

307

353

longer eligible to receive the encrypted password. The timeout,

308

354

checker program, and interval between checks can be configured

309

355

both globally and per client; see <citerefentry>

356

<refentrytitle>mandos.conf</refentrytitle>

357

310

358

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

311

359

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

312

360

</para>

315

363

316

364

<title>LOGGING</title>

317

365

<para>

318

The server will send log message with various severity levels to

319

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

366

The server will send log messaged with various severity levels

367

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

320

368

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

321

369

and also show them on the console.

322

370

</para>

334

382

<title>ENVIRONMENT</title>

335

383

336

384

337

385

338

386

339

387

<para>

340

388

To start the configured checker (see <xref

343

391

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

344

392

an absolute path is not given. See <citerefentry>

345

393

346

</citerefentry>.

394

</citerefentry>

347

395

</para>

348

396

</listitem>

349

397

</varlistentry>

379

427

</listitem>

380

428

</varlistentry>

381

429

382

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

430

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

383

431

384

432

<para>

385

433

The file containing the process id of

434

482

Debug mode is conflated with running in the foreground.

435

483

</para>

436

484

<para>

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.

485

The console log messages does not show a timestamp.

442

486

</para>

443

487

</refsect1>

444

488

449

493

Normal invocation needs no options:

450

494

</para>

451

495

<para>

452

<userinput>&COMMANDNAME;</userinput>

496

<userinput>mandos</userinput>

453

497

</para>

454

498

</informalexample>

455

499

462

506

<para>

463

507

464

508

465

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

509

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

466

510

467

511

</para>

468

512

</informalexample>

474

518

<para>

475

519

476

520

477

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

521

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

478

522

479

523

</para>

480

524

</informalexample>

487

531

<para>

488

532

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

489

533

should not in itself present any security risk to the host

490

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

491

soon after startup.

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.

492

536

</para>

493

537

</refsect2>

494

538

521

565

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

522

566

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

523

567

fake Mandos client with the keys from the non-encrypted

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

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

527

571

configuration file to omit any suspect clients, and restart

528

572

the server program.

529

573

</para>

537

581

538

582

539

583

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>

551

584

552

585

553

586

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

554

603

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

555

604

</term>

556

605

573

622

</varlistentry>

574

623

575

624

<term>

576

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

577

>GnuTLS</ulink>

625

<ulink

626

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

578

627

</term>

579

628

580

629

<para>

586

635

</varlistentry>

587

636

588

637

<term>

589

RFC 4291: <citetitle>IP Version 6 Addressing

590

Architecture</citetitle>

638

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

639

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

640

Unicast Addresses</citation>

591

641

</term>

592

642

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>

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>

617

649

</listitem>

618

650

</varlistentry>

619

651

620

652

<term>

621

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

622

Protocol Version 1.1</citetitle>

653

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

654

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

623

655

</term>

624

656

625

657

<para>

629

661

</varlistentry>

630

662

631

663

<term>

632

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

664

<citation>RFC 4880: <citetitle>OpenPGP Message

665

Format</citetitle></citation>

633

666

</term>

634

667

635

668

<para>

639

672

</varlistentry>

640

673

641

674

<term>

642

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

643

Security</citetitle>

675

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

676

Transport Layer Security</citetitle></citation>

644

677

</term>

645

678

646

679

<para>

652

685

</variablelist>

653

686

</refsect1>

654

687

</refentry>

655

656

657

658

659