/mandos/trunk : revision 237.4.1

To get this branch, use:

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

« back to all changes in this revision

Viewing changes to mandos-ctl.xml

Committer: Teddy Hogeborn
Date: 2010-09-28 18:39:30 UTC
mfrom: (449 mandos-local)
mto: (24.1.170 mandos) (237.4.29 release)
mto: This revision was merged to the branch mainline in revision 450.
Revision ID: teddy@fukt.bsnet.se-20100928183930-i0r0cb2e2v5w6dfe

Merge from trunk.  D-Bus usage is now standard, and there are two new
utilities (mandos-monitor and mandos-ctl) which uses it.  Also, a new
plugin for Plymouth.  Also fixes Debian bug #557076.

Show diffs side-by-side

added added

removed removed

mandos-ctl.xml

<?xml version="1.0" encoding="UTF-8"?>

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

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

<!ENTITY COMMANDNAME "mandos-ctl">

<!ENTITY TIMESTAMP "2010-09-26">

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

%common;

<title>Mandos Manual</title>

<productname>Mandos</productname>

<productnumber>&version;</productnumber>

<date>&TIMESTAMP;</date>

<firstname>Björn</firstname>

<surname>Påhlsson</surname>

<email>belorn@fukt.bsnet.se</email>

</address>

</author>

<firstname>Teddy</firstname>

<surname>Hogeborn</surname>

<email>teddy@fukt.bsnet.se</email>

</address>

</author>

</authorgroup>

<holder>Teddy Hogeborn</holder>

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

</copyright>

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

</refentryinfo>

<refentrytitle>&COMMANDNAME;</refentrytitle>

</refmeta>

<refname><command>&COMMANDNAME;</command></refname>

Control the operation of the Mandos server

</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

<group>

<arg choice="plain"><option>--enable</option></arg>

<sbr/>

<arg choice="plain"><option>--disable</option></arg>

</group>

<sbr/>

<group>

<arg choice="plain"><option>--bump-timeout</option></arg>

</group>

<sbr/>

<group>

<arg choice="plain"><option>--start-checker</option></arg>

</group>

<sbr/>

<group>

<arg choice="plain"><option>--stop-checker</option></arg>

</group>

<sbr/>

<group>

<arg choice="plain"><option>--remove</option></arg>

</group>

<sbr/>

<group>

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

<replaceable>COMMAND</replaceable></option></arg>

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

<replaceable>COMMAND</replaceable></option></arg>

</group>

<sbr/>

<group>

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

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

</group>

<sbr/>

<group>

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

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

100

101

</group>

102

<sbr/>

103

<group>

104

<arg choice="plain"><option>--approve-by-default</option

105

></arg>

106

<sbr/>

107

<arg choice="plain"><option>--deny-by-default</option></arg>

108

</group>

109

<sbr/>

110

<group>

111

<arg choice="plain"><option>--approval-delay

112

113

</group>

114

<sbr/>

115

<group>

116

<arg choice="plain"><option>--approval-duration

117

118

</group>

119

<sbr/>

120

<group>

121

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

122

123

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

124

125

</group>

126

<sbr/>

127

<group>

128

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

129

<replaceable>STRING</replaceable></option></arg>

130

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

131

<replaceable>STRING</replaceable></option></arg>

132

</group>

133

<sbr/>

134

<group>

135

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

136

<replaceable>FILENAME</replaceable></option></arg>

137

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

138

<replaceable>FILENAME</replaceable></option></arg>

139

</group>

140

<sbr/>

141

<group>

142

<arg choice="plain"><option>--approve</option></arg>

143

144

<sbr/>

145

146

147

</group>

148

<sbr/>

149

150

151

152

153

<replaceable>CLIENT</replaceable>

154

</arg>

155

</group>

156

</cmdsynopsis>

157

158

<command>&COMMANDNAME;</command>

159

<group>

160

<arg choice="plain"><option>--verbose</option></arg>

161

162

</group>

163

<group>

164

165

<replaceable>CLIENT</replaceable>

166

</arg>

167

</group>

168

</cmdsynopsis>

169

170

<command>&COMMANDNAME;</command>

171

172

<arg choice="plain"><option>--is-enabled</option></arg>

173

174

</group>

175

<arg choice='plain'><replaceable>CLIENT</replaceable></arg>

176

</cmdsynopsis>

177

178

<command>&COMMANDNAME;</command>

179

180

181

182

</group>

183

</cmdsynopsis>

184

185

<command>&COMMANDNAME;</command>

186

187

<arg choice="plain"><option>--version</option></arg>

188

189

</group>

190

</cmdsynopsis>

191

</refsynopsisdiv>

192

193

194

<title>DESCRIPTION</title>

195

<para>

196

<command>&COMMANDNAME;</command> is a program to control the

197

operation of the Mandos server <citerefentry><refentrytitle

198

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

199

</para>

200

<para>

201

This program can be used to change client settings, approve or

202

deny client requests, and to remove clients from the server.

203

</para>

204

</refsect1>

205

206

207

<title>PURPOSE</title>

208

<para>

209

The purpose of this is to enable <emphasis>remote and unattended

210

rebooting</emphasis> of client host computer with an

211

<emphasis>encrypted root file system</emphasis>. See <xref

212

linkend="overview"/> for details.

213

</para>

214

</refsect1>

215

216

217

<title>OPTIONS</title>

218

219

220

221

222

223

224

<para>

225

Show a help message and exit

226

</para>

227

</listitem>

228

</varlistentry>

229

230

231

<term><option>--enable</option></term>

232

233

234

<para>

235

Enable client(s). An enabled client will be eligble to

236

receive its secret.

237

</para>

238

</listitem>

239

</varlistentry>

240

241

242

<term><option>--disable</option></term>

243

244

245

<para>

246

Disable client(s). A disabled client will not be eligble

247

to receive its secret, and no checkers will be started for

248

it.

249

</para>

250

</listitem>

251

</varlistentry>

252

253

254

<term><option>--bump-timeout</option></term>

255

256

<para>

257

Bump the timeout of the specified client(s), just as if a

258

checker had completed successfully for it/them.

259

</para>

260

</listitem>

261

</varlistentry>

262

263

264

<term><option>--start-checker</option></term>

265

266

<para>

267

Start a new checker now for the specified client(s).

268

</para>

269

</listitem>

270

</varlistentry>

271

272

273

<term><option>--stop-checker</option></term>

274

275

<para>

276

Stop any running checker for the specified client(s).

277

</para>

278

</listitem>

279

</varlistentry>

280

281

282

<term><option>--remove</option></term>

283

284

285

<para>

286

Remove the specified client(s) from the server.

287

</para>

288

</listitem>

289

</varlistentry>

290

291

292

<term><option>--checker

293

<replaceable>COMMAND</replaceable></option></term>

294

<term><option>-c

295

<replaceable>COMMAND</replaceable></option></term>

296

297

<para>

298

Set the <varname>checker</varname> option of the specified

299

client(s); see <citerefentry><refentrytitle

300

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

301

>5</manvolnum></citerefentry>.

302

</para>

303

</listitem>

304

</varlistentry>

305

306

307

<term><option>--timeout

308

309

<term><option>-t

310

311

312

<para>

313

Set the <varname>timeout</varname> option of the specified

314

client(s); see <citerefentry><refentrytitle

315

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

316

>5</manvolnum></citerefentry>.

317

</para>

318

</listitem>

319

</varlistentry>

320

321

322

<term><option>--interval

323

324

<term><option>-i

325

326

327

<para>

328

Set the <varname>interval</varname> option of the

329

specified client(s); see <citerefentry><refentrytitle

330

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

331

>5</manvolnum></citerefentry>.

332

</para>

333

</listitem>

334

</varlistentry>

335

336

337

<term><option>--approve-by-default</option></term>

338

<term><option>--deny-by-default</option></term>

339

340

<para>

341

Set the <varname>approved_by_default</varname> option of

342

the specified client(s) to <literal>True</literal> or

343

<literal>False</literal>, respectively; see

344

<citerefentry><refentrytitle

345

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

346

>5</manvolnum></citerefentry>.

347

</para>

348

</listitem>

349

</varlistentry>

350

351

352

<term><option>--approval-delay

353

354

355

<para>

356

Set the <varname>approval_delay</varname> option of the

357

specified client(s); see <citerefentry><refentrytitle

358

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

359

>5</manvolnum></citerefentry>.

360

</para>

361

</listitem>

362

</varlistentry>

363

364

365

<term><option>--approval-duration

366

367

368

<para>

369

Set the <varname>approval_duration</varname> option of the

370

specified client(s); see <citerefentry><refentrytitle

371

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

372

>5</manvolnum></citerefentry>.

373

</para>

374

</listitem>

375

</varlistentry>

376

377

378

<term><option>--host

379

<replaceable>STRING</replaceable></option></term>

380

<term><option>-H

381

<replaceable>STRING</replaceable></option></term>

382

383

<para>

384

Set the <varname>host</varname> option of the specified

385

client(s); see <citerefentry><refentrytitle

386

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

387

>5</manvolnum></citerefentry>.

388

</para>

389

</listitem>

390

</varlistentry>

391

392

393

<term><option>--secret

394

<replaceable>FILENAME</replaceable></option></term>

395

<term><option>-s

396

<replaceable>FILENAME</replaceable></option></term>

397

398

<para>

399

Set the <varname>secfile</varname> option of the specified

400

client(s); see <citerefentry><refentrytitle

401

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

402

>5</manvolnum></citerefentry>.

403

</para>

404

</listitem>

405

</varlistentry>

406

407

408

<term><option>--approve</option></term>

409

410

411

<para>

412

Approve client(s) if currently waiting for approval.

413

</para>

414

</listitem>

415

</varlistentry>

416

417

418

419

420

421

<para>

422

Deny client(s) if currently waiting for approval.

423

</para>

424

</listitem>

425

</varlistentry>

426

427

428

429

430

431

<para>

432

Make the client-modifying options modify <emphasis

433

>all</emphasis> clients.

434

</para>

435

</listitem>

436

</varlistentry>

437

438

439

<term><option>--verbose</option></term>

440

441

442

<para>

443

Show all client settings, not just a subset.

444

</para>

445

</listitem>

446

</varlistentry>

447

448

449

<term><option>--is-enabled</option></term>

450

451

452

<para>

453

Check if a single client is enabled or not, and exit with

454

a successful exit status only if the client is enabled.

455

</para>

456

</listitem>

457

</varlistentry>

458

459

</variablelist>

460

</refsect1>

461

462

463

<title>OVERVIEW</title>

464

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

465

<para>

466

This program is a small utility to generate new OpenPGP keys for

467

new Mandos clients, and to generate sections for inclusion in

468

<filename>clients.conf</filename> on the server.

469

</para>

470

</refsect1>

471

472

473

<title>EXIT STATUS</title>

474

<para>

475

If the <option>--is-enabled</option> option is used, the exit

476

status will be 0 only if the specified client is enabled.

477

</para>

478

</refsect1>

479

480

481

482

483

484

485

486

487

<title>EXAMPLE</title>

488

489

<para>

490

To list all clients:

491

</para>

492

<para>

493

<userinput>&COMMANDNAME;</userinput>

494

</para>

495

</informalexample>

496

497

498

<para>

499

To list <emphasis>all</emphasis> settings for the clients

500

named <quote>foo1.example.org</quote> and <quote

501

>foo2.example.org</quote>:

502

</para>

503

<para>

504

505

506

<userinput>&COMMANDNAME; --verbose foo1.example.org foo2.example.org</userinput>

507

508

</para>

509

</informalexample>

510

511

512

<para>

513

To enable all clients:

514

</para>

515

<para>

516

<userinput>&COMMANDNAME; --enable --all</userinput>

517

</para>

518

</informalexample>

519

520

521

<para>

522

To change timeout and interval value for the clients

523

named <quote>foo1.example.org</quote> and <quote

524

>foo2.example.org</quote>:

525

</para>

526

<para>

527

528

529

<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>

530

531

</para>

532

</informalexample>

533

534

535

<para>

536

To approve all clients currently waiting for it:

537

</para>

538

<para>

539

<userinput>&COMMANDNAME; --approve --all</userinput>

540

</para>

541

</informalexample>

542

</refsect1>

543

544

545

<title>SECURITY</title>

546

<para>

547

This program must be permitted to access the Mandos server via

548

the D-Bus interface. This normally requires the root user, but

549

could be configured otherwise by reconfiguring the D-Bus server.

550

</para>

551

</refsect1>

552

553

554

555

<para>

556

<citerefentry><refentrytitle>mandos</refentrytitle>

557

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

558

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

559

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

560

<citerefentry><refentrytitle>mandos-monitor</refentrytitle>

561

562

</para>

563

</refsect1>

564

565

</refentry>

566

567

568

569

570

Older »