/mandos/trunk

« back to all changes in this revision

Viewing changes to plugins.d/mandos-client.xml

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

• reverse the comparison (237.4.32 to 876)
• stop comparing with revision 876

Show diffs side-by-side

added

removed

plugins.d/mandos-client.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-client">

5

 

<!ENTITY TIMESTAMP "2016-07-10">

 

5

<!ENTITY TIMESTAMP "2012-05-27">

6

6

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

7

7

%common;

8

8

]>

33

33

    <copyright>

34

34

      <year>2008</year>

35

35

      <year>2009</year>

36

 

      <year>2010</year>

37

 

      <year>2011</year>

38

36

      <year>2012</year>

39

 

      <year>2013</year>

40

 

      <year>2014</year>

41

 

      <year>2015</year>

42

 

      <year>2016</year>

43

37

      <holder>Teddy Hogeborn</holder>

44

38

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

45

39

    </copyright>

70

64

        ><replaceable>PORT</replaceable></option></arg>

71

65

      </group>

72

66

      <sbr/>

73

 

      <group rep='repeat'>

 

67

      <group>

74

68

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

75

 

        <replaceable>NAME</replaceable><arg rep='repeat'

76

 

        >,<replaceable>NAME</replaceable></arg></option></arg>

77

 

        <arg choice="plain"><option>-i <replaceable>NAME</replaceable

78

 

        ><arg rep='repeat'>,<replaceable>NAME</replaceable></arg

79

 

        ></option></arg>

 

69

        <replaceable>NAME</replaceable></option></arg>

 

70

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

 

71

        <replaceable>NAME</replaceable></option></arg>

80

72

      </group>

81

73

      <sbr/>

82

74

      <group>

102

94

      </arg>

103

95

      <sbr/>

104

96

      <arg>

105

 

        <option>--dh-params <replaceable>FILE</replaceable></option>

106

 

      </arg>

107

 

      <sbr/>

108

 

      <arg>

109

97

        <option>--delay <replaceable>SECONDS</replaceable></option>

110

98

      </arg>

111

99

      <sbr/>

149

137

      communicates with <citerefentry><refentrytitle

150

138

      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>

151

139

      to get a password.  In slightly more detail, this client program

152

 

      brings up network interfaces, uses the interfaces’ IPv6

153

 

      link-local addresses to get network connectivity, uses Zeroconf

154

 

      to find servers on the local network, and communicates with

155

 

      servers using TLS with an OpenPGP key to ensure authenticity and

 

140

      brings up a network interface, uses the interface’s IPv6

 

141

      link-local address to get network connectivity, uses Zeroconf to

 

142

      find servers on the local network, and communicates with servers

 

143

      using TLS with an OpenPGP key to ensure authenticity and

156

144

      confidentiality.  This client program keeps running, trying all

157

145

      servers on the network, until it receives a satisfactory reply

158

146

      or a TERM signal.  After all servers have been tried, all

160

148

      will wait indefinitely for new servers to appear.

161

149

    </para>

162

150

    <para>

163

 

      The network interfaces are selected like this: If any interfaces

164

 

      are specified using the <option>--interface</option> option,

165

 

      those interface are used.  Otherwise,

166

 

      <command>&COMMANDNAME;</command> will use all interfaces that

167

 

      are not loopback interfaces, are not point-to-point interfaces,

168

 

      are capable of broadcasting and do not have the NOARP flag (see

 

151

      The network interface is selected like this: If an interface is

 

152

      specified using the <option>--interface</option> option, that

 

153

      interface is used.  Otherwise, <command>&COMMANDNAME;</command>

 

154

      will choose any interface that is up and running and is not a

 

155

      loopback interface, is not a point-to-point interface, is

 

156

      capable of broadcasting and does not have the NOARP flag (see

169

157

      <citerefentry><refentrytitle>netdevice</refentrytitle>

170

158

      <manvolnum>7</manvolnum></citerefentry>).  (If the

171

159

      <option>--connect</option> option is used, point-to-point

172

 

      interfaces and non-broadcast interfaces are accepted.)  If any

173

 

      used interfaces are not up and running, they are first taken up

174

 

      (and later taken down again on program exit).

 

160

      interfaces and non-broadcast interfaces are accepted.)  If no

 

161

      acceptable interfaces are found, re-run the check but without

 

162

      the <quote>up and running</quote> requirement, and manually take

 

163

      the selected interface up (and later take it down on program

 

164

      exit).

175

165

    </para>

176

166

    <para>

177

 

      Before network interfaces are selected, all <quote>network

 

167

      Before a network interface is selected, all <quote>network

178

168

      hooks</quote> are run; see <xref linkend="network-hooks"/>.

179

169

    </para>

180

170

    <para>

228

218

            assumed to separate the address from the port number.

229

219

          </para>

230

220

          <para>

231

 

            Normally, Zeroconf would be used to locate Mandos servers,

232

 

            in which case this option would only be used when testing

233

 

            and debugging.

 

221

            This option is normally only useful for testing and

 

222

            debugging.

234

223

          </para>

235

224

        </listitem>

236

225

      </varlistentry>

237

226

      

238

227

      <varlistentry>

239

228

        <term><option>--interface=<replaceable

240

 

        >NAME</replaceable><arg rep='repeat'>,<replaceable

241

 

        >NAME</replaceable></arg></option></term>

 

229

        >NAME</replaceable></option></term>

242

230

        <term><option>-i

243

 

        <replaceable>NAME</replaceable><arg rep='repeat'>,<replaceable

244

 

        >NAME</replaceable></arg></option></term>

 

231

        <replaceable>NAME</replaceable></option></term>

245

232

        <listitem>

246

233

          <para>

247

 

            Comma separated list of network interfaces that will be

248

 

            brought up and scanned for Mandos servers to connect to.

249

 

            The default is the empty string, which will automatically

250

 

            use all appropriate interfaces.

 

234

            Network interface that will be brought up and scanned for

 

235

            Mandos servers to connect to.  The default is the empty

 

236

            string, which will automatically choose an appropriate

 

237

            interface.

251

238

          </para>

252

239

          <para>

253

 

            If the <option>--connect</option> option is used, and

254

 

            exactly one interface name is specified (except

255

 

            <quote><literal>none</literal></quote>), this specifies

256

 

            the interface to use to connect to the address given.

 

240

            If the <option>--connect</option> option is used, this

 

241

            specifies the interface to use to connect to the address

 

242

            given.

257

243

          </para>

258

244

          <para>

259

245

            Note that since this program will normally run in the

260

246

            initial RAM disk environment, the interface must be an

261

247

            interface which exists at that stage.  Thus, the interface

262

 

            can normally not be a pseudo-interface such as

263

 

            <quote>br0</quote> or <quote>tun0</quote>; such interfaces

264

 

            will not exist until much later in the boot process, and

265

 

            can not be used by this program, unless created by a

266

 

            <quote>network hook</quote> — see <xref

267

 

            linkend="network-hooks"/>.

 

248

            can not be a pseudo-interface such as <quote>br0</quote>

 

249

            or <quote>tun0</quote>; such interfaces will not exist

 

250

            until much later in the boot process, and can not be used

 

251

            by this program, unless created by a <quote>network

 

252

            hook</quote> — see <xref linkend="network-hooks"/>.

268

253

          </para>

269

254

          <para>

270

255

            <replaceable>NAME</replaceable> can be the string

271

 

            <quote><literal>none</literal></quote>; this will make

272

 

            <command>&COMMANDNAME;</command> only bring up interfaces

273

 

            specified <emphasis>before</emphasis> this string.  This

274

 

            is not recommended, and only meant for advanced users.

 

256

            <quote><literal>none</literal></quote>; this will not use

 

257

            any specific interface, and will not bring up an interface

 

258

            on startup.  This is not recommended, and only meant for

 

259

            advanced users.

275

260

          </para>

276

261

        </listitem>

277

262

      </varlistentry>

319

304

        <listitem>

320

305

          <para>

321

306

            Sets the number of bits to use for the prime number in the

322

 

            TLS Diffie-Hellman key exchange.  The default value is

323

 

            selected automatically based on the OpenPGP key.  Note

324

 

            that if the <option>--dh-params</option> option is used,

325

 

            the values from that file will be used instead.

326

 

          </para>

327

 

        </listitem>

328

 

      </varlistentry>

329

 

      

330

 

      <varlistentry>

331

 

        <term><option>--dh-params=<replaceable

332

 

        >FILE</replaceable></option></term>

333

 

        <listitem>

334

 

          <para>

335

 

            Specifies a PEM-encoded PKCS#3 file to read the parameters

336

 

            needed by the TLS Diffie-Hellman key exchange from.  If

337

 

            this option is not given, or if the file for some reason

338

 

            could not be used, the parameters will be generated on

339

 

            startup, which will take some time and processing power.

340

 

            Those using servers running under time, power or processor

341

 

            constraints may want to generate such a file in advance

342

 

            and use this option.

 

307

            TLS Diffie-Hellman key exchange.  Default is 1024.

343

308

          </para>

344

309

        </listitem>

345

310

      </varlistentry>

349

314

        >SECONDS</replaceable></option></term>

350

315

        <listitem>

351

316

          <para>

352

 

            After bringing a network interface up, the program waits

 

317

            After bringing the network interface up, the program waits

353

318

            for the interface to arrive in a <quote>running</quote>

354

319

            state before proceeding.  During this time, the kernel log

355

320

            level will be lowered to reduce clutter on the system

472

437

  

473

438

  <refsect1 id="environment">

474

439

    <title>ENVIRONMENT</title>

475

 

    <variablelist>

476

 

      <varlistentry>

477

 

        <term><envar>MANDOSPLUGINHELPERDIR</envar></term>

478

 

        <listitem>

479

 

          <para>

480

 

            This environment variable will be assumed to contain the

481

 

            directory containing any helper executables.  The use and

482

 

            nature of these helper executables, if any, is

483

 

            purposefully not documented.

484

 

        </para>

485

 

        </listitem>

486

 

      </varlistentry>

487

 

    </variablelist>

488

440

    <para>

489

 

      This program does not use any other environment variables, not

490

 

      even the ones provided by <citerefentry><refentrytitle

 

441

      This program does not use any environment variables, not even

 

442

      the ones provided by <citerefentry><refentrytitle

491

443

      >cryptsetup</refentrytitle><manvolnum>8</manvolnum>

492

444

    </citerefentry>.

493

445

    </para>

555

507

              It is not necessary to print any non-executable files

556

508

              already in the network hook directory, these will be

557

509

              copied implicitly if they otherwise satisfy the name

558

 

              requirements.

 

510

              requirement.

559

511

            </para>

560

512

          </listitem>

561

513

        </varlistentry>

595

547

          <term><envar>DEVICE</envar></term>

596

548

          <listitem>

597

549

            <para>

598

 

              The network interfaces, as specified to

 

550

              The network interface, as specified to

599

551

              <command>&COMMANDNAME;</command> by the

600

 

              <option>--interface</option> option, combined to one

601

 

              string and separated by commas.  If this is set, and

602

 

              does not contain the interface a hook will bring up,

603

 

              there is no reason for a hook to continue.

 

552

              <option>--interface</option> option.  If this is not the

 

553

              interface a hook will bring up, there is no reason for a

 

554

              hook to continue.

604

555

            </para>

605

556

          </listitem>

606

557

        </varlistentry>

693

644

    </variablelist>

694

645

  </refsect1>

695

646

  

696

 

  <refsect1 id="bugs">

697

 

    <title>BUGS</title>

698

 

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

699

 

  </refsect1>

 

647

<!--   <refsect1 id="bugs"> -->

 

648

<!--     <title>BUGS</title> -->

 

649

<!--     <para> -->

 

650

<!--     </para> -->

 

651

<!--   </refsect1> -->

700

652

  

701

653

  <refsect1 id="example">

702

654

    <title>EXAMPLE</title>

708

660

    </para>

709

661

    <informalexample>

710

662

      <para>

711

 

        Normal invocation needs no options, if the network interfaces

 

663

        Normal invocation needs no options, if the network interface

712

664

        can be automatically determined:

713

665

      </para>

714

666

      <para>

717

669

    </informalexample>

718

670

    <informalexample>

719

671

      <para>

720

 

        Search for Mandos servers (and connect to them) using one

721

 

        specific interface:

 

672

        Search for Mandos servers (and connect to them) using another

 

673

        interface:

722

674

      </para>

723

675

      <para>

724

676

        <!-- do not wrap this line -->

788

740

    <para>

789

741

      It will also help if the checker program on the server is

790

742

      configured to request something from the client which can not be

791

 

      spoofed by someone else on the network, like SSH server key

792

 

      fingerprints, and unlike unencrypted <acronym>ICMP</acronym>

793

 

      echo (<quote>ping</quote>) replies.

 

743

      spoofed by someone else on the network, unlike unencrypted

 

744

      <acronym>ICMP</acronym> echo (<quote>ping</quote>) replies.

794

745

    </para>

795

746

    <para>

796

747

      <emphasis>Note</emphasis>: This makes it completely insecure to

842

793

      </varlistentry>

843

794

      <varlistentry>

844

795

        <term>

845

 

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

 

796

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

 

797

          >GnuTLS</ulink>

846

798

        </term>

847

799

      <listitem>

848

800

        <para>

854

806

      </varlistentry>

855

807

      <varlistentry>

856

808

        <term>

857

 

          <ulink url="https://www.gnupg.org/related_software/gpgme/"

 

809

          <ulink url="http://www.gnupg.org/related_software/gpgme/"

858

810

                 >GPGME</ulink>

859

811

        </term>

860

812

        <listitem>

888

840

              <para>

889

841

                This client uses IPv6 link-local addresses, which are

890

842

                immediately usable since a link-local addresses is

891

 

                automatically assigned to a network interface when it

 

843

                automatically assigned to a network interfaces when it

892

844

                is brought up.

893

845

              </para>

894

846

            </listitem>

898

850

      </varlistentry>

899

851

      <varlistentry>

900

852

        <term>

901

 

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

902

 

          Protocol Version 1.2</citetitle>

 

853

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

 

854

          Protocol Version 1.1</citetitle>

903

855

        </term>

904

856

      <listitem>

905

857

        <para>

906

 

          TLS 1.2 is the protocol implemented by GnuTLS.

 

858

          TLS 1.1 is the protocol implemented by GnuTLS.

907

859

        </para>

908

860

      </listitem>

909

861

      </varlistentry>

920

872

      </varlistentry>

921

873

      <varlistentry>

922

874

        <term>

923

 

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

 

875

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

924

876

          Security</citetitle>

925

877

        </term>

926

878

      <listitem>

• Older »

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