/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 925)
• stop comparing with revision 925

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 "2018-02-08">

 

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

 

      <year>2017</year>

44

 

      <year>2018</year>

45

37

      <holder>Teddy Hogeborn</holder>

46

38

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

47

39

    </copyright>

72

64

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

73

65

      </group>

74

66

      <sbr/>

75

 

      <group rep='repeat'>

 

67

      <group>

76

68

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

77

 

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

78

 

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

79

 

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

80

 

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

81

 

        ></option></arg>

 

69

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

 

70

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

 

71

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

82

72

      </group>

83

73

      <sbr/>

84

74

      <group>

104

94

      </arg>

105

95

      <sbr/>

106

96

      <arg>

107

 

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

108

 

      </arg>

109

 

      <sbr/>

110

 

      <arg>

111

97

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

112

98

      </arg>

113

99

      <sbr/>

151

137

      communicates with <citerefentry><refentrytitle

152

138

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

153

139

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

154

 

      brings up network interfaces, uses the interfaces’ IPv6

155

 

      link-local addresses to get network connectivity, uses Zeroconf

156

 

      to find servers on the local network, and communicates with

157

 

      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

158

144

      confidentiality.  This client program keeps running, trying all

159

145

      servers on the network, until it receives a satisfactory reply

160

146

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

162

148

      will wait indefinitely for new servers to appear.

163

149

    </para>

164

150

    <para>

165

 

      The network interfaces are selected like this: If any interfaces

166

 

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

167

 

      those interface are used.  Otherwise,

168

 

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

169

 

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

170

 

      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

171

157

      <citerefentry><refentrytitle>netdevice</refentrytitle>

172

158

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

173

159

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

174

 

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

175

 

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

176

 

      (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).

177

165

    </para>

178

166

    <para>

179

 

      Before network interfaces are selected, all <quote>network

 

167

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

180

168

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

181

169

    </para>

182

170

    <para>

230

218

            assumed to separate the address from the port number.

231

219

          </para>

232

220

          <para>

233

 

            Normally, Zeroconf would be used to locate Mandos servers,

234

 

            in which case this option would only be used when testing

235

 

            and debugging.

 

221

            This option is normally only useful for testing and

 

222

            debugging.

236

223

          </para>

237

224

        </listitem>

238

225

      </varlistentry>

239

226

      

240

227

      <varlistentry>

241

228

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

242

 

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

243

 

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

 

229

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

244

230

        <term><option>-i

245

 

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

246

 

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

 

231

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

247

232

        <listitem>

248

233

          <para>

249

 

            Comma separated list of network interfaces that will be

250

 

            brought up and scanned for Mandos servers to connect to.

251

 

            The default is the empty string, which will automatically

252

 

            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.

253

238

          </para>

254

239

          <para>

255

 

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

256

 

            exactly one interface name is specified (except

257

 

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

258

 

            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.

259

243

          </para>

260

244

          <para>

261

245

            Note that since this program will normally run in the

262

246

            initial RAM disk environment, the interface must be an

263

247

            interface which exists at that stage.  Thus, the interface

264

 

            can normally not be a pseudo-interface such as

265

 

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

266

 

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

267

 

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

268

 

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

269

 

            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"/>.

270

253

          </para>

271

254

          <para>

272

255

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

273

 

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

274

 

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

275

 

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

276

 

            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.

277

260

          </para>

278

261

        </listitem>

279

262

      </varlistentry>

321

304

        <listitem>

322

305

          <para>

323

306

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

324

 

            TLS Diffie-Hellman key exchange.  The default value is

325

 

            selected automatically based on the OpenPGP key.  Note

326

 

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

327

 

            the values from that file will be used instead.

328

 

          </para>

329

 

        </listitem>

330

 

      </varlistentry>

331

 

      

332

 

      <varlistentry>

333

 

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

334

 

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

335

 

        <listitem>

336

 

          <para>

337

 

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

338

 

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

339

 

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

340

 

            could not be used, the parameters will be generated on

341

 

            startup, which will take some time and processing power.

342

 

            Those using servers running under time, power or processor

343

 

            constraints may want to generate such a file in advance

344

 

            and use this option.

 

307

            TLS Diffie-Hellman key exchange.  Default is 1024.

345

308

          </para>

346

309

        </listitem>

347

310

      </varlistentry>

351

314

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

352

315

        <listitem>

353

316

          <para>

354

 

            After bringing a network interface up, the program waits

 

317

            After bringing the network interface up, the program waits

355

318

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

356

319

            state before proceeding.  During this time, the kernel log

357

320

            level will be lowered to reduce clutter on the system

474

437

  

475

438

  <refsect1 id="environment">

476

439

    <title>ENVIRONMENT</title>

477

 

    <variablelist>

478

 

      <varlistentry>

479

 

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

480

 

        <listitem>

481

 

          <para>

482

 

            This environment variable will be assumed to contain the

483

 

            directory containing any helper executables.  The use and

484

 

            nature of these helper executables, if any, is

485

 

            purposefully not documented.

486

 

        </para>

487

 

        </listitem>

488

 

      </varlistentry>

489

 

    </variablelist>

490

440

    <para>

491

 

      This program does not use any other environment variables, not

492

 

      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

493

443

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

494

444

    </citerefentry>.

495

445

    </para>

557

507

              It is not necessary to print any non-executable files

558

508

              already in the network hook directory, these will be

559

509

              copied implicitly if they otherwise satisfy the name

560

 

              requirements.

 

510

              requirement.

561

511

            </para>

562

512

          </listitem>

563

513

        </varlistentry>

597

547

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

598

548

          <listitem>

599

549

            <para>

600

 

              The network interfaces, as specified to

 

550

              The network interface, as specified to

601

551

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

602

 

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

603

 

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

604

 

              does not contain the interface a hook will bring up,

605

 

              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.

606

555

            </para>

607

556

          </listitem>

608

557

        </varlistentry>

695

644

    </variablelist>

696

645

  </refsect1>

697

646

  

698

 

  <refsect1 id="bugs">

699

 

    <title>BUGS</title>

700

 

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

701

 

  </refsect1>

 

647

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

 

648

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

 

649

<!--     <para> -->

 

650

<!--     </para> -->

 

651

<!--   </refsect1> -->

702

652

  

703

653

  <refsect1 id="example">

704

654

    <title>EXAMPLE</title>

710

660

    </para>

711

661

    <informalexample>

712

662

      <para>

713

 

        Normal invocation needs no options, if the network interfaces

 

663

        Normal invocation needs no options, if the network interface

714

664

        can be automatically determined:

715

665

      </para>

716

666

      <para>

719

669

    </informalexample>

720

670

    <informalexample>

721

671

      <para>

722

 

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

723

 

        specific interface:

 

672

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

 

673

        interface:

724

674

      </para>

725

675

      <para>

726

676

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

790

740

    <para>

791

741

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

792

742

      configured to request something from the client which can not be

793

 

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

794

 

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

795

 

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

 

743

      spoofed by someone else on the network, unlike unencrypted

 

744

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

796

745

    </para>

797

746

    <para>

798

747

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

844

793

      </varlistentry>

845

794

      <varlistentry>

846

795

        <term>

847

 

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

 

796

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

 

797

          >GnuTLS</ulink>

848

798

        </term>

849

799

      <listitem>

850

800

        <para>

856

806

      </varlistentry>

857

807

      <varlistentry>

858

808

        <term>

859

 

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

 

809

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

860

810

                 >GPGME</ulink>

861

811

        </term>

862

812

        <listitem>

890

840

              <para>

891

841

                This client uses IPv6 link-local addresses, which are

892

842

                immediately usable since a link-local addresses is

893

 

                automatically assigned to a network interface when it

 

843

                automatically assigned to a network interfaces when it

894

844

                is brought up.

895

845

              </para>

896

846

            </listitem>

900

850

      </varlistentry>

901

851

      <varlistentry>

902

852

        <term>

903

 

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

904

 

          Protocol Version 1.2</citetitle>

 

853

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

 

854

          Protocol Version 1.1</citetitle>

905

855

        </term>

906

856

      <listitem>

907

857

        <para>

908

 

          TLS 1.2 is the protocol implemented by GnuTLS.

 

858

          TLS 1.1 is the protocol implemented by GnuTLS.

909

859

        </para>

910

860

      </listitem>

911

861

      </varlistentry>

922

872

      </varlistentry>

923

873

      <varlistentry>

924

874

        <term>

925

 

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

 

875

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

926

876

          Security</citetitle>

927

877

        </term>

928

878

      <listitem>

• Older »

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