/mandos/trunk

« back to all changes in this revision

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

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

• reverse the comparison (237.4.29 to 787)
• stop comparing with revision 787

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 "2015-07-20">

 

5

<!ENTITY TIMESTAMP "2012-01-01">

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

37

      <holder>Teddy Hogeborn</holder>

43

38

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

44

39

    </copyright>

69

64

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

70

65

      </group>

71

66

      <sbr/>

72

 

      <group rep='repeat'>

 

67

      <group>

73

68

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

74

 

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

75

 

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

76

 

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

77

 

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

78

 

        ></option></arg>

 

69

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

 

70

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

 

71

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

79

72

      </group>

80

73

      <sbr/>

81

74

      <group>

101

94

      </arg>

102

95

      <sbr/>

103

96

      <arg>

104

 

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

105

 

      </arg>

106

 

      <sbr/>

107

 

      <arg>

108

97

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

109

98

      </arg>

110

99

      <sbr/>

148

137

      communicates with <citerefentry><refentrytitle

149

138

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

150

139

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

151

 

      brings up network interfaces, uses the interfaces’ IPv6

152

 

      link-local addresses to get network connectivity, uses Zeroconf

153

 

      to find servers on the local network, and communicates with

154

 

      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

155

144

      confidentiality.  This client program keeps running, trying all

156

145

      servers on the network, until it receives a satisfactory reply

157

146

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

159

148

      will wait indefinitely for new servers to appear.

160

149

    </para>

161

150

    <para>

162

 

      The network interfaces are selected like this: If any interfaces

163

 

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

164

 

      those interface are used.  Otherwise,

165

 

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

166

 

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

167

 

      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

168

157

      <citerefentry><refentrytitle>netdevice</refentrytitle>

169

158

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

170

159

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

171

 

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

172

 

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

173

 

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

174

165

    </para>

175

166

    <para>

176

 

      Before network interfaces are selected, all <quote>network

 

167

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

177

168

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

178

169

    </para>

179

170

    <para>

227

218

            assumed to separate the address from the port number.

228

219

          </para>

229

220

          <para>

230

 

            Normally, Zeroconf would be used to locate Mandos servers,

231

 

            in which case this option would only be used when testing

232

 

            and debugging.

 

221

            This option is normally only useful for testing and

 

222

            debugging.

233

223

          </para>

234

224

        </listitem>

235

225

      </varlistentry>

236

226

      

237

227

      <varlistentry>

238

228

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

239

 

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

240

 

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

 

229

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

241

230

        <term><option>-i

242

 

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

243

 

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

 

231

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

244

232

        <listitem>

245

233

          <para>

246

 

            Comma separated list of network interfaces that will be

247

 

            brought up and scanned for Mandos servers to connect to.

248

 

            The default is the empty string, which will automatically

249

 

            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.

250

238

          </para>

251

239

          <para>

252

 

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

253

 

            exactly one interface name is specified (except

254

 

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

255

 

            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.

256

243

          </para>

257

244

          <para>

258

245

            Note that since this program will normally run in the

259

246

            initial RAM disk environment, the interface must be an

260

247

            interface which exists at that stage.  Thus, the interface

261

 

            can normally not be a pseudo-interface such as

262

 

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

263

 

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

264

 

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

265

 

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

266

 

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

267

253

          </para>

268

254

          <para>

269

255

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

270

 

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

271

 

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

272

 

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

273

 

            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.

274

260

          </para>

275

261

        </listitem>

276

262

      </varlistentry>

318

304

        <listitem>

319

305

          <para>

320

306

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

321

 

            TLS Diffie-Hellman key exchange.  The default value is

322

 

            selected automatically based on the OpenPGP key.  Note

323

 

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

324

 

            the values from that file will be used instead.

325

 

          </para>

326

 

        </listitem>

327

 

      </varlistentry>

328

 

      

329

 

      <varlistentry>

330

 

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

331

 

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

332

 

        <listitem>

333

 

          <para>

334

 

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

335

 

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

336

 

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

337

 

            could not be used, the parameters will be generated on

338

 

            startup, which will take some time and processing power.

339

 

            Those using servers running under time, power or processor

340

 

            constraints may want to generate such a file in advance

341

 

            and use this option.

 

307

            TLS Diffie-Hellman key exchange.  Default is 1024.

342

308

          </para>

343

309

        </listitem>

344

310

      </varlistentry>

348

314

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

349

315

        <listitem>

350

316

          <para>

351

 

            After bringing a network interface up, the program waits

 

317

            After bringing the network interface up, the program waits

352

318

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

353

319

            state before proceeding.  During this time, the kernel log

354

320

            level will be lowered to reduce clutter on the system

471

437

  

472

438

  <refsect1 id="environment">

473

439

    <title>ENVIRONMENT</title>

474

 

    <variablelist>

475

 

      <varlistentry>

476

 

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

477

 

        <listitem>

478

 

          <para>

479

 

            This environment variable will be assumed to contain the

480

 

            directory containing any helper executables.  The use and

481

 

            nature of these helper executables, if any, is

482

 

            purposefully not documented.

483

 

        </para>

484

 

        </listitem>

485

 

      </varlistentry>

486

 

    </variablelist>

487

440

    <para>

488

 

      This program does not use any other environment variables, not

489

 

      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

490

443

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

491

444

    </citerefentry>.

492

445

    </para>

554

507

              It is not necessary to print any non-executable files

555

508

              already in the network hook directory, these will be

556

509

              copied implicitly if they otherwise satisfy the name

557

 

              requirements.

 

510

              requirement.

558

511

            </para>

559

512

          </listitem>

560

513

        </varlistentry>

594

547

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

595

548

          <listitem>

596

549

            <para>

597

 

              The network interfaces, as specified to

 

550

              The network interface, as specified to

598

551

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

599

 

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

600

 

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

601

 

              does not contain the interface a hook will bring up,

602

 

              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.

603

555

            </para>

604

556

          </listitem>

605

557

        </varlistentry>

708

660

    </para>

709

661

    <informalexample>

710

662

      <para>

711

 

        Normal invocation needs no options, if the network interfaces

712

 

        can be automatically determined:

 

663

        Normal invocation needs no options, if the network interface

 

664

        is <quote>eth0</quote>:

713

665

      </para>

714

666

      <para>

715

667

        <userinput>&COMMANDNAME;</userinput>

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

889

840

              <para>

890

841

                This client uses IPv6 link-local addresses, which are

891

842

                immediately usable since a link-local addresses is

892

 

                automatically assigned to a network interface when it

 

843

                automatically assigned to a network interfaces when it

893

844

                is brought up.

894

845

              </para>

895

846

            </listitem>

• Older »

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