/mandos/trunk : revision 85

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

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

127

134

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

128

135

linkend="overview"/> for details.

129

136

</para>

130

137

131

138

</refsect1>

132

139

133

140

134

141

<title>OPTIONS</title>

135

142

136

143

137

144

138

139

145

140

146

141

147

<para>

142

148

Show a help message and exit

143

149

</para>

144

150

</listitem>

145

151

</varlistentry>

146

147

148

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

149

150

151

152

153

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

154

</listitem>

155

</varlistentry>

156

157

158

<term><option>--address

159

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

160

<term><option>-a

161

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

162

163

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

164

</listitem>

165

</varlistentry>

166

167

168

<term><option>--port

169

170

<term><option>-p

171

172

173

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

174

</listitem>

175

</varlistentry>

176

177

178

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

179

198

180

199

<para>

181

200

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

183

202

</para>

184

203

</listitem>

185

204

</varlistentry>

186

187

188

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

189

190

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

191

</listitem>

192

</varlistentry>

193

194

195

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

196

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

197

198

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

199

</listitem>

200

</varlistentry>

201

202

203

<term><option>--servicename

204

205

206

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

207

xpointer="servicename"/>

208

</listitem>

209

</varlistentry>

210

211

212

<term><option>--configdir

213

<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>. You only need

241

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

242

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

243

which would not normally be useful. If there are name

244

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

245

newer server will automatically rename itself to

246

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

247

therefore, this option is not needed in that case.

248

</para>

249

</listitem>

250

</varlistentry>

251

252

253

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

254

</literal></term>

214

255

215

256

<para>

216

257

Directory to search for configuration files. Default is

224

265

</varlistentry>

225

266

226

267

227

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

268

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

228

269

229

270

<para>

230

271

Prints the program version and exit.

236

277

237

278

238

279

<title>OVERVIEW</title>

239

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

280

&OVERVIEW;

240

281

<para>

241

282

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

242

283

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

243

<acronym>RAM</acronym> disk environment.

284

RAM disk environment.

244

285

</para>

245

286

</refsect1>

246

287

275

316

276

317

</row>

277

318

<row>

278

319

279

320

280

321

</row>

281

322

<row>

311

352

longer eligible to receive the encrypted password. The timeout,

312

353

checker program, and interval between checks can be configured

313

354

both globally and per client; see <citerefentry>

355

<refentrytitle>mandos.conf</refentrytitle>

356

314

357

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

315

358

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

316

359

</para>

319

362

320

363

<title>LOGGING</title>

321

364

<para>

322

The server will send log message with various severity levels to

323

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

365

The server will send log messaged with various severity levels

366

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

324

367

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

325

368

and also show them on the console.

326

369

</para>

338

381

<title>ENVIRONMENT</title>

339

382

340

383

341

384

342

385

343

386

<para>

344

387

To start the configured checker (see <xref

347

390

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

348

391

an absolute path is not given. See <citerefentry>

349

392

350

</citerefentry>.

393

</citerefentry>

351

394

</para>

352

395

</listitem>

353

396

</varlistentry>

449

492

Normal invocation needs no options:

450

493

</para>

451

494

<para>

452

<userinput>&COMMANDNAME;</userinput>

495

<userinput>mandos</userinput>

453

496

</para>

454

497

</informalexample>

455

498

462

505

<para>

463

506

464

507

465

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

508

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

466

509

467

510

</para>

468

511

</informalexample>

474

517

<para>

475

518

476

519

477

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

520

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

478

521

479

522

</para>

480

523

</informalexample>

518

561

re-read its client list from its configuration file and again

519

562

regard all clients therein as valid, and hence eligible to

520

563

receive their passwords. Therefore, be careful when

521

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

522

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

523

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

527

configuration file to omit any suspect clients, and restart

528

the server program.

564

restarting servers if you suspect that a client has, in fact,

565

been compromised by parties who may now be running a fake

566

Mandos client with the keys from the non-encrypted initial RAM

567

image of the client host. What should be done in that case

568

(if restarting the server program really is necessary) is to

569

stop the server program, edit the configuration file to omit

570

any suspect clients, and restart the server program.

529

571

</para>

530

572

<para>

531

573

For more details on client-side security, see

537

579

538

580

539

581

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

582

552

583

553

584

<term>

585

586

<refentrytitle>password-request</refentrytitle>

587

<manvolnum>8mandos</manvolnum>

588

</citerefentry>

589

</term>

590

591

<para>

592

This is the actual program which talks to this server.

593

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

594

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

595

fully started system.

596

</para>

597

</listitem>

598

</varlistentry>

599

600

<term>

554

601

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

555

602

</term>

556

603

573

620

</varlistentry>

574

621

575

622

<term>

576

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

577

>GnuTLS</ulink>

623

<ulink

624

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

578

625

</term>

579

626

580

627

<para>

586

633

</varlistentry>

587

634

588

635

<term>

589

RFC 4291: <citetitle>IP Version 6 Addressing

590

Architecture</citetitle>

636

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

637

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

638

Unicast Addresses</citation>

591

639

</term>

592

640

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>

641

<para>

642

The clients use IPv6 link-local addresses, which are

643

immediately usable since a link-local addresses is

644

automatically assigned to a network interfaces when it is

645

brought up.

646

</para>

617

647

</listitem>

618

648

</varlistentry>

619

649

620

650

<term>

621

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

622

Protocol Version 1.1</citetitle>

651

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

652

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

623

653

</term>

624

654

625

655

<para>

629

659

</varlistentry>

630

660

631

661

<term>

632

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

662

<citation>RFC 4880: <citetitle>OpenPGP Message

663

Format</citetitle></citation>

633

664

</term>

634

665

635

666

<para>

639

670

</varlistentry>

640

671

641

672

<term>

642

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

643

Security</citetitle>

673

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

674

Transport Layer Security</citetitle></citation>

644

675

</term>

645

676

646

677

<para>

652

683

</variablelist>

653

684

</refsect1>

654

685

</refentry>

655

656

657

658

659