/mandos/trunk

« back to all changes in this revision

Viewing changes to mandos.xml

• browse files at revision 237.4.4
• compare with another revision
• download diff
• download tarball
• view history from revision 237.4.4

• reverse the comparison (237.4.4 to 781)
• stop comparing with revision 781

Show diffs side-by-side

added

removed

mandos.xml

2

2

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

3

3

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

4

4

<!ENTITY COMMANDNAME "mandos">

5

 

<!ENTITY TIMESTAMP "2015-07-20">

 

5

<!ENTITY TIMESTAMP "2010-09-26">

6

6

<!ENTITY % common SYSTEM "common.ent">

7

7

%common;

8

8

]>

19

19

        <firstname>Björn</firstname>

20

20

        <surname>Påhlsson</surname>

21

21

        <address>

22

 

          <email>belorn@recompile.se</email>

 

22

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

23

23

        </address>

24

24

      </author>

25

25

      <author>

26

26

        <firstname>Teddy</firstname>

27

27

        <surname>Hogeborn</surname>

28

28

        <address>

29

 

          <email>teddy@recompile.se</email>

 

29

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

30

30

        </address>

31

31

      </author>

32

32

    </authorgroup>

34

34

      <year>2008</year>

35

35

      <year>2009</year>

36

36

      <year>2010</year>

37

 

      <year>2011</year>

38

 

      <year>2012</year>

39

 

      <year>2013</year>

40

 

      <year>2014</year>

41

 

      <year>2015</year>

42

37

      <holder>Teddy Hogeborn</holder>

43

38

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

44

39

    </copyright>

98

93

      <arg><option>--no-dbus</option></arg>

99

94

      <sbr/>

100

95

      <arg><option>--no-ipv6</option></arg>

101

 

      <sbr/>

102

 

      <arg><option>--no-restore</option></arg>

103

 

      <sbr/>

104

 

      <arg><option>--statedir

105

 

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

106

 

      <sbr/>

107

 

      <arg><option>--socket

108

 

      <replaceable>FD</replaceable></option></arg>

109

 

      <sbr/>

110

 

      <arg><option>--foreground</option></arg>

111

 

      <sbr/>

112

 

      <arg><option>--no-zeroconf</option></arg>

113

96

    </cmdsynopsis>

114

97

    <cmdsynopsis>

115

98

      <command>&COMMANDNAME;</command>

133

116

    <para>

134

117

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

135

118

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

136

 

      client host computers. For an introduction, see

137

 

      <citerefentry><refentrytitle>intro</refentrytitle>

138

 

      <manvolnum>8mandos</manvolnum></citerefentry>. The Mandos server

139

 

      uses Zeroconf to announce itself on the local network, and uses

140

 

      TLS to communicate securely with and to authenticate the

141

 

      clients.  The Mandos server uses IPv6 to allow Mandos clients to

142

 

      use IPv6 link-local addresses, since the clients will probably

143

 

      not have any other addresses configured (see <xref

144

 

      linkend="overview"/>).  Any authenticated client is then given

145

 

      the stored pre-encrypted password for that specific client.

 

119

      client host computers.  The Mandos server uses Zeroconf to

 

120

      announce itself on the local network, and uses TLS to

 

121

      communicate securely with and to authenticate the clients.  The

 

122

      Mandos server uses IPv6 to allow Mandos clients to use IPv6

 

123

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

 

124

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

 

125

      Any authenticated client is then given the stored pre-encrypted

 

126

      password for that specific client.

146

127

    </para>

147

128

  </refsect1>

148

129

  

291

272

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

292

273

        </listitem>

293

274

      </varlistentry>

294

 

      

295

 

      <varlistentry>

296

 

        <term><option>--no-restore</option></term>

297

 

        <listitem>

298

 

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

299

 

          <para>

300

 

            See also <xref linkend="persistent_state"/>.

301

 

          </para>

302

 

        </listitem>

303

 

      </varlistentry>

304

 

      

305

 

      <varlistentry>

306

 

        <term><option>--statedir

307

 

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

308

 

        <listitem>

309

 

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

310

 

        </listitem>

311

 

      </varlistentry>

312

 

      

313

 

      <varlistentry>

314

 

        <term><option>--socket

315

 

        <replaceable>FD</replaceable></option></term>

316

 

        <listitem>

317

 

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

318

 

        </listitem>

319

 

      </varlistentry>

320

 

      

321

 

      <varlistentry>

322

 

        <term><option>--foreground</option></term>

323

 

        <listitem>

324

 

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

325

 

                      xpointer="foreground"/>

326

 

        </listitem>

327

 

      </varlistentry>

328

 

      

329

 

      <varlistentry>

330

 

        <term><option>--no-zeroconf</option></term>

331

 

        <listitem>

332

 

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

333

 

        </listitem>

334

 

      </varlistentry>

335

 

      

336

275

    </variablelist>

337

276

  </refsect1>

338

277

  

412

351

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

413

352

      longer eligible to receive the encrypted password.  (Manual

414

353

      intervention is required to re-enable a client.)  The timeout,

415

 

      extended timeout, checker program, and interval between checks

416

 

      can be configured both globally and per client; see

417

 

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

418

 

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

 

354

      checker program, and interval between checks can be configured

 

355

      both globally and per client; see <citerefentry>

 

356

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

 

357

      <manvolnum>5</manvolnum></citerefentry>.  A client successfully

 

358

      receiving its password will also be treated as a successful

 

359

      checker run.

419

360

    </para>

420

361

  </refsect1>

421

362

  

443

384

    <title>LOGGING</title>

444

385

    <para>

445

386

      The server will send log message with various severity levels to

446

 

      <filename class="devicefile">/dev/log</filename>.  With the

 

387

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

447

388

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

448

389

      and also show them on the console.

449

390

    </para>

450

391

  </refsect1>

451

392

  

452

 

  <refsect1 id="persistent_state">

453

 

    <title>PERSISTENT STATE</title>

454

 

    <para>

455

 

      Client settings, initially read from

456

 

      <filename>clients.conf</filename>, are persistent across

457

 

      restarts, and run-time changes will override settings in

458

 

      <filename>clients.conf</filename>.  However, if a setting is

459

 

      <emphasis>changed</emphasis> (or a client added, or removed) in

460

 

      <filename>clients.conf</filename>, this will take precedence.

461

 

    </para>

462

 

  </refsect1>

463

 

  

464

393

  <refsect1 id="dbus_interface">

465

394

    <title>D-BUS INTERFACE</title>

466

395

    <para>

528

457

        </listitem>

529

458

      </varlistentry>

530

459

      <varlistentry>

531

 

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

 

460

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

532

461

        <listitem>

533

462

          <para>

534

463

            The file containing the process id of the

535

464

            <command>&COMMANDNAME;</command> process started last.

536

 

            <emphasis >Note:</emphasis> If the <filename

537

 

            class="directory">/run</filename> directory does not

538

 

            exist, <filename>/var/run/mandos.pid</filename> will be

539

 

            used instead.

540

 

          </para>

541

 

        </listitem>

542

 

      </varlistentry>

543

 

      <varlistentry>

544

 

        <term><filename class="devicefile">/dev/log</filename></term>

545

 

      </varlistentry>

546

 

      <varlistentry>

547

 

        <term><filename

548

 

        class="directory">/var/lib/mandos</filename></term>

549

 

        <listitem>

550

 

          <para>

551

 

            Directory where persistent state will be saved.  Change

552

 

            this with the <option>--statedir</option> option.  See

553

 

            also the <option>--no-restore</option> option.

554

465

          </para>

555

466

        </listitem>

556

467

      </varlistentry>

584

495

      backtrace.  This could be considered a feature.

585

496

    </para>

586

497

    <para>

 

498

      Currently, if a client is disabled due to having timed out, the

 

499

      server does not record this fact onto permanent storage.  This

 

500

      has some security implications, see <xref linkend="clients"/>.

 

501

    </para>

 

502

    <para>

587

503

      There is no fine-grained control over logging and debug output.

588

504

    </para>

589

505

    <para>

 

506

      Debug mode is conflated with running in the foreground.

 

507

    </para>

 

508

    <para>

 

509

      The console log messages do not show a time stamp.

 

510

    </para>

 

511

    <para>

590

512

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

591

513

      keys.

592

514

    </para>

605

527

    <informalexample>

606

528

      <para>

607

529

        Run the server in debug mode, read configuration files from

608

 

        the <filename class="directory">~/mandos</filename> directory,

609

 

        and use the Zeroconf service name <quote>Test</quote> to not

610

 

        collide with any other official Mandos server on this host:

 

530

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

 

531

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

 

532

        any other official Mandos server on this host:

611

533

      </para>

612

534

      <para>

613

535

 

662

584

        compromised if they are gone for too long.

663

585

      </para>

664

586

      <para>

 

587

        If a client is compromised, its downtime should be duly noted

 

588

        by the server which would therefore disable the client.  But

 

589

        if the server was ever restarted, it would re-read its client

 

590

        list from its configuration file and again regard all clients

 

591

        therein as enabled, and hence eligible to receive their

 

592

        passwords.  Therefore, be careful when restarting servers if

 

593

        it is suspected that a client has, in fact, been compromised

 

594

        by parties who may now be running a fake Mandos client with

 

595

        the keys from the non-encrypted initial <acronym>RAM</acronym>

 

596

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

 

597

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

 

598

        stop the server program, edit the configuration file to omit

 

599

        any suspect clients, and restart the server program.

 

600

      </para>

 

601

      <para>

665

602

        For more details on client-side security, see

666

603

        <citerefentry><refentrytitle>mandos-client</refentrytitle>

667

604

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

672

609

  <refsect1 id="see_also">

673

610

    <title>SEE ALSO</title>

674

611

    <para>

675

 

      <citerefentry><refentrytitle>intro</refentrytitle>

676

 

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

677

 

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

678

 

      <manvolnum>5</manvolnum></citerefentry>,

679

 

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

680

 

      <manvolnum>5</manvolnum></citerefentry>,

681

 

      <citerefentry><refentrytitle>mandos-client</refentrytitle>

682

 

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

683

 

      <citerefentry><refentrytitle>sh</refentrytitle>

684

 

      <manvolnum>1</manvolnum></citerefentry>

 

612

      <citerefentry>

 

613

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

 

614

        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>

 

615

        <refentrytitle>mandos.conf</refentrytitle>

 

616

        <manvolnum>5</manvolnum></citerefentry>, <citerefentry>

 

617

        <refentrytitle>mandos-client</refentrytitle>

 

618

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

 

619

        <refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum>

 

620

      </citerefentry>

685

621

    </para>

686

622

    <variablelist>

687

623

      <varlistentry>

708

644

      </varlistentry>

709

645

      <varlistentry>

710

646

        <term>

711

 

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

 

647

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

 

648

          >GnuTLS</ulink>

712

649

        </term>

713

650

      <listitem>

714

651

        <para>

752

689

      </varlistentry>

753

690

      <varlistentry>

754

691

        <term>

755

 

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

756

 

          Protocol Version 1.2</citetitle>

 

692

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

 

693

          Protocol Version 1.1</citetitle>

757

694

        </term>

758

695

      <listitem>

759

696

        <para>

760

 

          TLS 1.2 is the protocol implemented by GnuTLS.

 

697

          TLS 1.1 is the protocol implemented by GnuTLS.

761

698

        </para>

762

699

      </listitem>

763

700

      </varlistentry>

773

710

      </varlistentry>

774

711

      <varlistentry>

775

712

        <term>

776

 

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

777

 

          Security (TLS) Authentication</citetitle>

 

713

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

 

714

          Security</citetitle>

778

715

        </term>

779

716

      <listitem>

780

717

        <para>

• Older »

Loggerhead is a web-based interface for Breezy
Version: 2.0.2.dev0