/mandos/release

« back to all changes in this revision

Viewing changes to mandos.xml

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

• reverse the comparison (334 to 237.7.23)
• stop comparing with revision 237.7.23

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 "2011-02-27">

 

5

<!ENTITY TIMESTAMP "2016-02-28">

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@fukt.bsnet.se</email>

 

22

          <email>belorn@recompile.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@fukt.bsnet.se</email>

 

29

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

30

30

        </address>

31

31

      </author>

32

32

    </authorgroup>

35

35

      <year>2009</year>

36

36

      <year>2010</year>

37

37

      <year>2011</year>

 

38

      <year>2012</year>

 

39

      <year>2013</year>

 

40

      <year>2014</year>

 

41

      <year>2015</year>

 

42

      <year>2016</year>

38

43

      <holder>Teddy Hogeborn</holder>

39

44

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

40

45

    </copyright>

94

99

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

95

100

      <sbr/>

96

101

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

 

102

      <sbr/>

 

103

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

 

104

      <sbr/>

 

105

      <arg><option>--statedir

 

106

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

 

107

      <sbr/>

 

108

      <arg><option>--socket

 

109

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

 

110

      <sbr/>

 

111

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

 

112

      <sbr/>

 

113

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

97

114

    </cmdsynopsis>

98

115

    <cmdsynopsis>

99

116

      <command>&COMMANDNAME;</command>

117

134

    <para>

118

135

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

119

136

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

120

 

      client host computers.  The Mandos server uses Zeroconf to

121

 

      announce itself on the local network, and uses TLS to

122

 

      communicate securely with and to authenticate the clients.  The

123

 

      Mandos server uses IPv6 to allow Mandos clients to use IPv6

124

 

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

125

 

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

126

 

      Any authenticated client is then given the stored pre-encrypted

127

 

      password for that specific client.

 

137

      client host computers. For an introduction, see

 

138

      <citerefentry><refentrytitle>intro</refentrytitle>

 

139

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

 

140

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

 

141

      TLS to communicate securely with and to authenticate the

 

142

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

 

143

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

 

144

      not have any other addresses configured (see <xref

 

145

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

 

146

      the stored pre-encrypted password for that specific client.

128

147

    </para>

129

148

  </refsect1>

130

149

  

273

292

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

274

293

        </listitem>

275

294

      </varlistentry>

 

295

      

 

296

      <varlistentry>

 

297

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

 

298

        <listitem>

 

299

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

 

300

          <para>

 

301

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

 

302

          </para>

 

303

        </listitem>

 

304

      </varlistentry>

 

305

      

 

306

      <varlistentry>

 

307

        <term><option>--statedir

 

308

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

 

309

        <listitem>

 

310

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

 

311

        </listitem>

 

312

      </varlistentry>

 

313

      

 

314

      <varlistentry>

 

315

        <term><option>--socket

 

316

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

 

317

        <listitem>

 

318

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

 

319

        </listitem>

 

320

      </varlistentry>

 

321

      

 

322

      <varlistentry>

 

323

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

 

324

        <listitem>

 

325

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

 

326

                      xpointer="foreground"/>

 

327

        </listitem>

 

328

      </varlistentry>

 

329

      

 

330

      <varlistentry>

 

331

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

 

332

        <listitem>

 

333

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

 

334

        </listitem>

 

335

      </varlistentry>

 

336

      

276

337

    </variablelist>

277

338

  </refsect1>

278

339

  

352

413

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

353

414

      longer eligible to receive the encrypted password.  (Manual

354

415

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

355

 

      checker program, and interval between checks can be configured

356

 

      both globally and per client; see <citerefentry>

357

 

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

358

 

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

359

 

      receiving its password will also be treated as a successful

360

 

      checker run.

 

416

      extended timeout, checker program, and interval between checks

 

417

      can be configured both globally and per client; see

 

418

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

 

419

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

361

420

    </para>

362

421

  </refsect1>

363

422

  

385

444

    <title>LOGGING</title>

386

445

    <para>

387

446

      The server will send log message with various severity levels to

388

 

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

 

447

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

389

448

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

390

449

      and also show them on the console.

391

450

    </para>

392

451

  </refsect1>

393

452

  

 

453

  <refsect1 id="persistent_state">

 

454

    <title>PERSISTENT STATE</title>

 

455

    <para>

 

456

      Client settings, initially read from

 

457

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

 

458

      restarts, and run-time changes will override settings in

 

459

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

 

460

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

 

461

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

 

462

    </para>

 

463

  </refsect1>

 

464

  

394

465

  <refsect1 id="dbus_interface">

395

466

    <title>D-BUS INTERFACE</title>

396

467

    <para>

458

529

        </listitem>

459

530

      </varlistentry>

460

531

      <varlistentry>

461

 

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

 

532

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

462

533

        <listitem>

463

534

          <para>

464

535

            The file containing the process id of the

465

536

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

466

 

          </para>

467

 

        </listitem>

468

 

      </varlistentry>

469

 

      <varlistentry>

470

 

        <term><filename>/dev/log</filename></term>

 

537

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

 

538

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

 

539

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

 

540

            used instead.

 

541

          </para>

 

542

        </listitem>

 

543

      </varlistentry>

 

544

      <varlistentry>

 

545

        <term><filename

 

546

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

 

547

        <listitem>

 

548

          <para>

 

549

            Directory where persistent state will be saved.  Change

 

550

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

 

551

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

 

552

          </para>

 

553

        </listitem>

 

554

      </varlistentry>

 

555

      <varlistentry>

 

556

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

471

557

        <listitem>

472

558

          <para>

473

559

            The Unix domain socket to where local syslog messages are

496

582

      backtrace.  This could be considered a feature.

497

583

    </para>

498

584

    <para>

499

 

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

500

 

      server does not record this fact onto permanent storage.  This

501

 

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

502

 

    </para>

503

 

    <para>

504

585

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

505

586

    </para>

506

587

    <para>

507

 

      Debug mode is conflated with running in the foreground.

508

 

    </para>

509

 

    <para>

510

 

      The console log messages do not show a time stamp.

511

 

    </para>

512

 

    <para>

513

588

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

514

589

      keys.

515

590

    </para>

528

603

    <informalexample>

529

604

      <para>

530

605

        Run the server in debug mode, read configuration files from

531

 

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

532

 

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

533

 

        any other official Mandos server on this host:

 

606

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

 

607

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

 

608

        collide with any other official Mandos server on this host:

534

609

      </para>

535

610

      <para>

536

611

 

585

660

        compromised if they are gone for too long.

586

661

      </para>

587

662

      <para>

588

 

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

589

 

        by the server which would therefore disable the client.  But

590

 

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

591

 

        list from its configuration file and again regard all clients

592

 

        therein as enabled, and hence eligible to receive their

593

 

        passwords.  Therefore, be careful when restarting servers if

594

 

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

595

 

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

596

 

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

597

 

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

598

 

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

599

 

        stop the server program, edit the configuration file to omit

600

 

        any suspect clients, and restart the server program.

601

 

      </para>

602

 

      <para>

603

663

        For more details on client-side security, see

604

664

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

605

665

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

610

670

  <refsect1 id="see_also">

611

671

    <title>SEE ALSO</title>

612

672

    <para>

613

 

      <citerefentry>

614

 

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

615

 

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

616

 

        <refentrytitle>mandos.conf</refentrytitle>

617

 

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

618

 

        <refentrytitle>mandos-client</refentrytitle>

619

 

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

620

 

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

621

 

      </citerefentry>

 

673

      <citerefentry><refentrytitle>intro</refentrytitle>

 

674

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

 

675

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

 

676

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

 

677

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

 

678

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

 

679

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

 

680

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

 

681

      <citerefentry><refentrytitle>sh</refentrytitle>

 

682

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

622

683

    </para>

623

684

    <variablelist>

624

685

      <varlistentry>

645

706

      </varlistentry>

646

707

      <varlistentry>

647

708

        <term>

648

 

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

649

 

          >GnuTLS</ulink>

 

709

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

650

710

        </term>

651

711

      <listitem>

652

712

        <para>

690

750

      </varlistentry>

691

751

      <varlistentry>

692

752

        <term>

693

 

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

694

 

          Protocol Version 1.1</citetitle>

 

753

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

 

754

          Protocol Version 1.2</citetitle>

695

755

        </term>

696

756

      <listitem>

697

757

        <para>

698

 

          TLS 1.1 is the protocol implemented by GnuTLS.

 

758

          TLS 1.2 is the protocol implemented by GnuTLS.

699

759

        </para>

700

760

      </listitem>

701

761

      </varlistentry>

711

771

      </varlistentry>

712

772

      <varlistentry>

713

773

        <term>

714

 

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

715

 

          Security</citetitle>

 

774

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

 

775

          Security (TLS) Authentication</citetitle>

716

776

        </term>

717

777

      <listitem>

718

778

        <para>

• Older »

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