/mandos/trunk : revision 505.2.13

To get this branch, use:

bzr branch
http://bzr.recompile.se/loggerhead/mandos/trunk

« back to all changes in this revision

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

Committer: Björn Påhlsson
Date: 2011-12-20 20:13:36 UTC
mfrom: (505.3.26 client-network-hooks)
mto: This revision was merged to the branch mainline in revision 525.
Revision ID: belorn@recompile.se-20111220201336-zs7sj3inc9wtioau

merge

Show diffs side-by-side

added added

removed removed

plugins.d/mandos-client.xml

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

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

<!ENTITY COMMANDNAME "mandos-client">

<!ENTITY TIMESTAMP "2011-10-03">

<!ENTITY TIMESTAMP "2011-11-27">

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

%common;

102

</arg>

103

<sbr/>

104

<arg>

105

<option>--network-hook-dir

106

107

</arg>

108

<sbr/>

109

<arg>

105

110

<option>--debug</option>

106

111

</arg>

107

112

</cmdsynopsis>

143

148

will wait indefinitely for new servers to appear.

144

149

</para>

145

150

<para>

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

157

<citerefentry><refentrytitle>netdevice</refentrytitle>

158

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

159

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

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

165

</para>

166

<para>

167

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

168

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

169

</para>

170

<para>

146

171

This program is not meant to be run directly; it is really meant

147

172

to run as a plugin of the <application>Mandos</application>

148

173

<citerefentry><refentrytitle>plugin-runner</refentrytitle>

223

248

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

224

249

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

225

250

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

226

by this program.

251

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

252

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

227

253

</para>

228

254

<para>

229

255

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

311

337

</para>

312

338

</listitem>

313

339

</varlistentry>

340

341

342

<term><option>--network-hook-dir=<replaceable

343

>DIR</replaceable></option></term>

344

345

<para>

346

Network hook directory. The default directory is

347

<quote><filename class="directory"

348

>/lib/mandos/network-hooks.d</filename></quote>.

349

</para>

350

</listitem>

351

</varlistentry>

314

352

315

353

316

354

<term><option>--debug</option></term>

377

415

<refentrytitle>plugin-runner</refentrytitle>

378

416

<manvolnum>8mandos</manvolnum></citerefentry>) is used to run

379

417

both this program and others in in parallel,

380

<emphasis>one</emphasis> of which will prompt for passwords on

381

the system console.

418

<emphasis>one</emphasis> of which (<citerefentry>

419

<refentrytitle>password-prompt</refentrytitle>

420

<manvolnum>8mandos</manvolnum></citerefentry>) will prompt for

421

passwords on the system console.

382

422

</para>

383

423

</refsect1>

384

424

405

445

</para>

406

446

</refsect1>

407

447

448

449

<title>NETWORK HOOKS</title>

450

<para>

451

If a network interface like a bridge or tunnel is required to

452

find a Mandos server, this requires the interface to be up and

453

running before <command>&COMMANDNAME;</command> starts looking

454

for Mandos servers. This can be accomplished by creating a

455

<quote>network hook</quote> program, and placing it in a special

456

directory.

457

</para>

458

<para>

459

Before the network is used (and again before program exit), any

460

runnable programs found in the network hook directory are run

461

with the argument <quote><literal>start</literal></quote> or

462

<quote><literal>stop</literal></quote>. This should bring up or

463

down, respectively, any network interface which

464

<command>&COMMANDNAME;</command> should use.

465

</para>

466

467

<title>REQUIREMENTS</title>

468

<para>

469

A network hook must be an executable file, and its name must

470

consist entirely of upper and lower case letters, digits,

471

underscores, periods, and hyphens.

472

</para>

473

<para>

474

A network hook will receive one argument, which can be one of

475

the following:

476

</para>

477

478

479

<term><literal>start</literal></term>

480

481

<para>

482

This should make the network hook create (if necessary)

483

and bring up a network interface.

484

</para>

485

</listitem>

486

</varlistentry>

487

488

489

490

<para>

491

This should make the network hook take down a network

492

interface, and delete it if it did not exist previously.

493

</para>

494

</listitem>

495

</varlistentry>

496

497

<term><literal>files</literal></term>

498

499

<para>

500

This should make the network hook print, <emphasis>one

501

file per line</emphasis>, all the files needed for it to

502

run. (These files will be copied into the initial RAM

503

filesystem.) Typical use is for a network hook which is

504

a shell script to print its needed binaries.

505

</para>

506

<para>

507

It is not necessary to print any non-executable files

508

already in the network hook directory, these will be

509

copied implicitly if they otherwise satisfy the name

510

requirement.

511

</para>

512

</listitem>

513

</varlistentry>

514

515

<term><literal>modules</literal></term>

516

517

<para>

518

This should make the network hook print, <emphasis>on

519

separate lines</emphasis>, all the kernel modules needed

520

for it to run. (These modules will be copied into the

521

initial RAM filesystem.) For instance, a tunnel

522

interface needs the

523

<quote><literal>tun</literal></quote> module.

524

</para>

525

</listitem>

526

</varlistentry>

527

</variablelist>

528

<para>

529

The network hook will be provided with a number of environment

530

variables:

531

</para>

532

533

534

<term><envar>MANDOSNETHOOKDIR</envar></term>

535

536

<para>

537

The network hook directory, specified to

538

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

539

<option>--network-hook-dir</option> option. Note: this

540

should <emphasis>always</emphasis> be used by the

541

network hook to refer to itself or any files in the hook

542

directory it may require.

543

</para>

544

</listitem>

545

</varlistentry>

546

547

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

548

549

<para>

550

The network interface, as specified to

551

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

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.

555

</para>

556

</listitem>

557

</varlistentry>

558

559

560

561

<para>

562

This will be the same as the first argument;

563

i.e. <quote><literal>start</literal></quote>,

564

<quote><literal>stop</literal></quote>,

565

<quote><literal>files</literal></quote>, or

566

<quote><literal>modules</literal></quote>.

567

</para>

568

</listitem>

569

</varlistentry>

570

571

<term><envar>VERBOSITY</envar></term>

572

573

<para>

574

This will be the <quote><literal>1</literal></quote> if

575

the <option>--debug</option> option is passed to

576

<command>&COMMANDNAME;</command>, otherwise

577

<quote><literal>0</literal></quote>.

578

</para>

579

</listitem>

580

</varlistentry>

581

582

<term><envar>DELAY</envar></term>

583

584

<para>

585

This will be the same as the <option>--delay</option>

586

option passed to <command>&COMMANDNAME;</command>.

587

</para>

588

</listitem>

589

</varlistentry>

590

</variablelist>

591

<para>

592

A hook may not read from standard input, and should be

593

restrictive in printing to standard output or standard error

594

unless <varname>VERBOSITY</varname> is

595

<quote><literal>1</literal></quote>.

596

</para>

597

</refsect2>

598

</refsect1>

599

408

600

409

601

<title>FILES</title>

410

602

422

614

</para>

423

615

</listitem>

424

616

</varlistentry>

617

618

<term><filename

619

class="directory">/lib/mandos/network-hooks.d</filename></term>

620

621

<para>

622

Directory where network hooks are located. Change this

623

with the <option>--network-hook-dir</option> option. See

624

<xref linkend="network-hooks"/>.

625

</para>

626

</listitem>

627

</varlistentry>

425

628

</variablelist>

426

629

</refsect1>

427

630

Older »