/mandos/trunk : revision 120

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

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>

66

67

67

68

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

68

69

69

Sends encrypted passwords to authenticated Mandos clients

70

Gives encrypted passwords to authenticated Mandos clients

70

71

</refpurpose>

71

72

</refnamediv>

72

73

74

74

75

75

76

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

77

<group>

78

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

79

80

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

81

82

</group>

83

<sbr/>

84

<group>

85

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

86

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

87

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

88

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

89

</group>

90

<sbr/>

91

<group>

92

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

93

94

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

95

96

</group>

97

<sbr/>

98

<arg><option>--priority

99

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

100

<sbr/>

101

<arg><option>--servicename

102

103

<sbr/>

104

<arg><option>--configdir

105

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

106

<sbr/>

107

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

93

108

</cmdsynopsis>

94

109

95

110

<command>&COMMANDNAME;</command>

96

111

97

98

112

113

99

114

</group>

100

115

</cmdsynopsis>

101

116

102

117

<command>&COMMANDNAME;</command>

103

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

118

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

104

119

</cmdsynopsis>

105

120

106

121

<command>&COMMANDNAME;</command>

107

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

122

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

108

123

</cmdsynopsis>

109

124

</refsynopsisdiv>

110

125

142

157

143

158

144

159

145

160

161

146

162

147

163

<para>

148

164

Show a help message and exit

151

167

</varlistentry>

152

168

153

169

154

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

155

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

170

171

172

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

173

156

174

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>

175

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

164

176

</listitem>

165

177

</varlistentry>

166

178

168

180

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

169

181

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

170

182

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>

183

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

181

184

</listitem>

182

185

</varlistentry>

183

186

185

188

186

189

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

187

190

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>

191

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

193

192

</listitem>

194

193

</varlistentry>

195

194

206

205

207

206

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

208

207

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>

208

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

214

209

</listitem>

215

210

</varlistentry>

216

211

218

213

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

219

214

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

220

215

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>

216

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

231

217

</listitem>

232

218

</varlistentry>

233

219

235

221

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

236

222

</literal></term>

237

223

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>

224

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

225

xpointer="servicename"/>

250

226

</listitem>

251

227

</varlistentry>

252

228

278

254

279

255

280

256

<title>OVERVIEW</title>

281

&OVERVIEW;

257

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

282

258

<para>

283

259

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

284

260

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

317

293

318

294

</row>

319

295

<row>

320

296

321

297

322

298

</row>

323

299

<row>

353

329

longer eligible to receive the encrypted password. The timeout,

354

330

checker program, and interval between checks can be configured

355

331

both globally and per client; see <citerefentry>

356

<refentrytitle>mandos.conf</refentrytitle>

357

358

332

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

359

333

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

360

334

</para>

363

337

364

338

<title>LOGGING</title>

365

339

<para>

366

The server will send log messaged with various severity levels

367

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

340

The server will send log message with various severity levels to

341

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

368

342

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

369

343

and also show them on the console.

370

344

</para>

382

356

<title>ENVIRONMENT</title>

383

357

384

358

385

359

386

360

387

361

<para>

388

362

To start the configured checker (see <xref

391

365

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

392

366

an absolute path is not given. See <citerefentry>

393

367

394

</citerefentry>

368

</citerefentry>.

395

369

</para>

396

370

</listitem>

397

371

</varlistentry>

493

467

Normal invocation needs no options:

494

468

</para>

495

469

<para>

496

<userinput>mandos</userinput>

470

<userinput>&COMMANDNAME;</userinput>

497

471

</para>

498

472

</informalexample>

499

473

506

480

<para>

507

481

508

482

509

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

483

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

510

484

511

485

</para>

512

486

</informalexample>

518

492

<para>

519

493

520

494

521

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

495

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

522

496

523

497

</para>

524

498

</informalexample>

581

555

582

556

583

557

558

<para>

559

560

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

561

562

<refentrytitle>mandos.conf</refentrytitle>

563

564

<refentrytitle>password-request</refentrytitle>

565

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

566

567

</citerefentry>

568

</para>

584

569

585

570

586

571

<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

572

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

604

573

</term>

605

574

622

591

</varlistentry>

623

592

624

593

<term>

625

<ulink

626

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

594

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

595

>GnuTLS</ulink>

627

596

</term>

628

597

629

598

<para>

635

604

</varlistentry>

636

605

637

606

<term>

638

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

639

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

640

Unicast Addresses</citation>

607

RFC 4291: <citetitle>IP Version 6 Addressing

608

Architecture</citetitle>

641

609

</term>

642

610

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>

611

612

613

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

614

Addresses</citetitle></term>

615

616

</varlistentry>

617

618

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

619

Address</citetitle></term>

620

621

</varlistentry>

622

623

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

624

Addresses</citetitle></term>

625

626

<para>

627

The clients use IPv6 link-local addresses, which are

628

immediately usable since a link-local addresses is

629

automatically assigned to a network interfaces when it

630

is brought up.

631

</para>

632

</listitem>

633

</varlistentry>

634

</variablelist>

649

635

</listitem>

650

636

</varlistentry>

651

637

652

638

<term>

653

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

654

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

639

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

640

Protocol Version 1.1</citetitle>

655

641

</term>

656

642

657

643

<para>

661

647

</varlistentry>

662

648

663

649

<term>

664

<citation>RFC 4880: <citetitle>OpenPGP Message

665

Format</citetitle></citation>

650

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

666

651

</term>

667

652

668

653

<para>

672

657

</varlistentry>

673

658

674

659

<term>

675

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

676

Transport Layer Security</citetitle></citation>

660

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

661

Security</citetitle>

677

662

</term>

678

663

679

664

<para>

685

670

</variablelist>

686

671

</refsect1>

687

672

</refentry>

673

674

675

676

677