/mandos/release : revision 100

To get this branch, use:

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

« back to all changes in this revision

Viewing changes to mandos-clients.conf.xml

Committer: Teddy Hogeborn
Date: 2008-08-24 10:52:46 UTC
Revision ID: teddy@fukt.bsnet.se-20080824105246-4gu1o1q6sdjvqcyb

* mandos (fingerprint): Bug fix: Remove some temporary debugging code.

files added:
mandos-keygen.xml

mandos-options.xml

overview.xml

files removed:
network-protocol.txt

files modified:
Makefile

TODO

clients.conf

mandos

mandos-clients.conf.xml

mandos-keygen

mandos.conf

mandos.conf.xml

mandos.xml

plugin-runner.c

plugin-runner.xml

plugins.d/password-prompt.c

plugins.d/password-prompt.xml

plugins.d/password-request.c

plugins.d/password-request.xml

Show diffs side-by-side

added added

removed removed

mandos-clients.conf.xml

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

<?xml-stylesheet type="text/xsl"

href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>

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

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

<!ENTITY VERSION "1.0">

<title>&CONFNAME;</title>

<productname>&CONFNAME;</productname>

<productnumber>&VERSION;</productnumber>

</authorgroup>

<holder>Teddy Hogeborn & Björn Påhlsson</holder>

<holder>Teddy Hogeborn</holder>

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

</copyright>

<para>

<refname><filename>&CONFNAME;</filename></refname>

Configuration file for Mandos clients

Configuration file for the Mandos server

</refpurpose>

</refnamediv>

<title>DESCRIPTION</title>

<para>

The file &CONFPATH; is the configuration file for mandos where

each client that will be abel to use the service need to be

specified. The configuration file is looked on at the startup of

the service, so to reenable timedout clients one need to only

restart the server. The format starts with a section under []

which is eather <literal>[DEFAULT]</literal> or a client

name. Values is set through the use of VAR = VALUE pair. Values

may not be empty.

The file &CONFPATH; is the configuration file for <citerefentry

><refentrytitle>mandos</refentrytitle>

<manvolnum>8</manvolnum></citerefentry>, read by it at startup,

where each client that will be able to use the service needs to

be listed. All clients listed will be regarded as valid, even

if a client was declared invalid in a previous run of the

server.

</para>

<para>

The format starts with a <literal>[<replaceable>section

header</replaceable>]</literal> which is either

<literal>[DEFAULT]</literal> or <literal>[<replaceable>client

name</replaceable>]</literal>. The <replaceable>client

name</replaceable> can be anything, and is not tied to a host

name. Following the section header is any number of

<quote><varname><replaceable>option</replaceable

></varname>=<replaceable>value</replaceable></quote> entries,

with continuations in the style of RFC 822. <quote><varname

100

><replaceable>option</replaceable></varname>: <replaceable

101

>value</replaceable></quote> is also accepted. Note that

102

leading whitespace is removed from values. Values can contain

103

format strings which refer to other values in the same section,

104

or values in the <quote>DEFAULT</quote> section (see <xref

105

linkend="expansion"/>). Lines beginning with <quote>#</quote>

106

or <quote>;</quote> are ignored and may be used to provide

107

comments.

108

</para>

109

</refsect1>

<title>DEFAULTS</title>

110

111

112

<title>OPTIONS</title>

113

<para>

The paramters for <literal>[DEFAULT]</literal> are:

114

The possible options are:

115

</para>

116

100

117

101

118

102

119

103

<term><literal>timeout</literal></term>

120

<term><literal><varname>timeout</varname></literal></term>

104

121

105

<para>

106

This option allows you to override the default timeout

107

that clients will get. By default mandos will use 1hr.

122

<synopsis><literal>timeout = </literal><replaceable

123

>TIME</replaceable>

124

</synopsis>

125

<para>

126

The timeout is how long the server will wait for a

127

successful checker run until a client is considered

128

invalid - that is, ineligible to get the data this server

129

holds. By default Mandos will use 1 hour.

130

</para>

131

<para>

132

The <replaceable>TIME</replaceable> is specified as a

133

space-separated number of values, each of which is a

134

number and a one-character suffix. The suffix must be one

135

of <quote>d</quote>, <quote>s</quote>, <quote>m</quote>,

136

<quote>h</quote>, and <quote>w</quote> for days, seconds,

137

minutes, hours, and weeks, respectively. The values are

138

added together to give the total time value, so all of

139

<quote><literal>330s</literal></quote>,

140

<quote><literal>110s 110s 110s</literal></quote>, and

141

<quote><literal>5m 30s</literal></quote> will give a value

142

of five minutes and thirty seconds.

108

143

</para>

109

144

</listitem>

110

145

</varlistentry>

111

146

112

147

113

<term><literal>interval</literal></term>

148

<term><literal><varname>interval</varname></literal></term>

114

149

115

<para>

116

This option allows you to override the default interval

117

used between checkups for disconnected clients. By default

118

mandos will use 5m.

150

<synopsis><literal>interval = </literal><replaceable

151

>TIME</replaceable>

152

</synopsis>

153

<para>

154

How often to run the checker to confirm that a client is

155

still up. <emphasis>Note:</emphasis> a new checker will

156

not be started if an old one is still running. The server

157

will wait for a checker to complete until the above

158

<quote><varname>timeout</varname></quote> occurs, at which

159

time the client will be marked invalid, and any running

160

checker killed. The default interval is 5 minutes.

161

</para>

162

<para>

163

The format of <replaceable>TIME</replaceable> is the same

164

as for <varname>timeout</varname> above.

119

165

</para>

120

166

</listitem>

121

167

</varlistentry>

123

169

124

170

<term><literal>checker</literal></term>

125

171

172

<synopsis><literal>checker = </literal><replaceable

173

>COMMAND</replaceable>

174

</synopsis>

126

175

<para>

127

176

This option allows you to override the default shell

128

command that the server will use to check up if the client

129

is still up. By default mandos will "fping -q -- %%(host)s"

177

command that the server will use to check if the client is

178

still up. The output of the command will be ignored, only

179

the exit code is checked. The command will be run using

180

181

<option>-c</option></command></quote>. The default

182

command is <quote><literal><command>fping</command>

183

184

%(host)s</literal></quote>.

185

</para>

186

<para>

187

In addition to normal start time expansion, this option

188

will also be subject to runtime expansion; see <xref

189

linkend="expansion"/>.

130

190

</para>

131

191

</listitem>

132

192

</varlistentry>

133

193

134

</variablelist>

135

</refsect1>

136

137

138

<title>CLIENTS</title>

139

<para>

140

The paramters for clients are:

141

</para>

142

143

144

145

194

146

195

<term><literal>fingerprint</literal></term>

147

196

197

<synopsis><literal>fingerprint = </literal><replaceable

198

>HEXSTRING</replaceable>

199

</synopsis>

148

200

<para>

149

This option sets the openpgp fingerprint that identifies

150

the public certificate that clients authenticates themself

151

through gnutls. The string need to be in hex-decimal form.

201

This option sets the OpenPGP fingerprint that identifies

202

the public key that clients authenticate themselves with

203

through TLS. The string needs to be in hexidecimal form,

204

but spaces or upper/lower case are not significant.

152

205

</para>

153

206

</listitem>

154

207

</varlistentry>

156

209

157

210

<term><literal>secret</literal></term>

158

211

159

<para>

160

Base 64 encoded OpenPGP encrypted password encrypted by

161

the clients openpgp certificate.

212

<synopsis><literal>secret = </literal><replaceable

213

>BASE64_ENCODED_DATA</replaceable>

214

</synopsis>

215

<para>

216

If present, this option must be set to a string of

217

base64-encoded binary data. It will be decoded and sent

218

to the client matching the above

219

<option>fingerprint</option>. This should, of course, be

220

OpenPGP encrypted data, decryptable only by the client.

221

222

223

224

225

</para>

226

<para>

227

Note: this value of this option will probably run over

228

many lines, and will then have to use the fact that a line

229

beginning with white space adds to the value of the

230

previous line, RFC 822-style.

162

231

</para>

163

232

</listitem>

164

233

</varlistentry>

204

273

205

274

</variablelist>

206

275

</refsect1>

276

277

278

<title>EXPANSION</title>

279

<para>

280

There are two forms of expansion: Start time expansion and

281

runtime expansion.

282

</para>

283

284

<title>START TIME EXPANSION</title>

285

<para>

286

Any string in an option value of the form

287

<quote><literal>%(<replaceable>foo</replaceable>)s</literal

288

></quote> will be replaced by the value of the option

289

<varname>foo</varname> either in the same section, or, if it

290

does not exist there, the <literal>[DEFAULT]</literal>

291

section. This is done at start time, when the configuration

292

file is read.

293

</para>

294

<para>

295

Note that this means that, in order to include an actual

296

percent character (<quote>%</quote>) in an option value, two

297

percent characters in a row (<quote>%%</quote>) must be

298

entered.

299

</para>

300

</refsect2>

301

302

<title>RUNTIME EXPANSION</title>

303

<para>

304

This is currently only done for the <varname>checker</varname>

305

option.

306

</para>

307

<para>

308

Any string in an option value of the form

309

<quote><literal>%%(<replaceable>foo</replaceable>)s</literal

310

></quote> will be replaced by the value of the attribute

311

<varname>foo</varname> of the internal

312

<quote><classname>Client</classname></quote> object. See the

313

source code for details, and let the authors know of any

314

attributes that are useful so they may be preserved to any new

315

versions of this software.

316

</para>

317

<para>

318

Note that this means that, in order to include an actual

319

percent character (<quote>%</quote>) in a

320

<varname>checker</varname> options, <emphasis>four</emphasis>

321

percent characters in a row (<quote>%%%%</quote>) must be

322

entered. Also, a bad format here will lead to an immediate

323

but <emphasis>silent</emphasis> run-time fatal exit; debug

324

mode is needed to track down an error of this kind.

325

</para>

326

</refsect2>

207

327

208

209

<title>EXAMPLES</title>

328

</refsect1>

329

330

331

<title>FILES</title>

332

<para>

333

The file described here is &CONFPATH;

334

</para>

335

</refsect1>

336

337

338

339

<para>

340

The format for specifying times for <varname>timeout</varname>

341

and <varname>interval</varname> is not very good.

342

</para>

343

<para>

344

The difference between

345

<literal>%%(<replaceable>foo</replaceable>)s</literal> and

346

<literal>%(<replaceable>foo</replaceable>)s</literal> is

347

obscure.

348

</para>

349

</refsect1>

350

351

352

<title>EXAMPLE</title>

210

353

211

354

212

355

[DEFAULT]

213

356

timeout = 1h

214

357

interval = 5m

215

checker = fping -q -- %%(host)s

358

checker = fping -q -- %(host)s

216

359

217

[example_client]

360

# Client "foo"

361

[foo]

218

362

fingerprint = 7788 2722 5BA7 DE53 9C5A 7CFA 59CF F7CD BD9A 5920

219

220

363

secret =

221

364

hQIOA6QdEjBs2L/HEAf/TCyrDe5Xnm9esa+Pb/vWF9CUqfn4srzVgSu234

222

365

REJMVv7lBSrPE2132Lmd2gqF1HeLKDJRSVxJpt6xoWOChGHg+TMyXDxK+N

234

377

4T2zw4dxS5NswXWU0sVEXxjs6PYxuIiCTL7vdpx8QjBkrPWDrAbcMyBr2O

235

378

QlnHIvPzEArRQLo=

236

379

=iHhv

237

238

host = localhost

380

host = foo.example.org

239

381

interval = 5m

382

383

# Client "bar"

384

[bar]

385

fingerprint = 3e393aeaefb84c7e89e2f547b3a107558fca3a27

386

secfile = /etc/mandos/bar-secret.txt.asc

387

240

388

</programlisting>

241

389

</informalexample>

242

390

</refsect1>

243

244

245

<title>FILES</title>

246

<para>

247

The file described here is &CONFPATH;

248

</para>

249

</refsect1>

391

250

392

</refentry>

Older »