/mandos/trunk : revision 126

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/password-prompt.xml

Committer: Teddy Hogeborn
Date: 2008-08-31 10:44:32 UTC
Revision ID: teddy@fukt.bsnet.se-20080831104432-9hzi47foc7tlmade

* plugins.d/password-prompt.xml (OPTIONS): Move <replaceable> tags to
                                           inside <option> tags.
                                           Moved long options before
                                           short.

files added:
.bzrignore

COPYING

initramfs-tools-hook

initramfs-tools-hook-conf

initramfs-tools-script

mandos-keygen

mandos-keygen.xml

mandos-options.xml

overview.xml

plugins.d/usplash

files removed:
network-protocol.txt

files renamed:
mandos-client.c => plugin-runner.c

mandos-client.xml => plugin-runner.xml

files modified:
Makefile

TODO

clients.conf

mandos

mandos-clients.conf.xml

mandos.conf

mandos.conf.xml

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

plugins.d/password-prompt.xml

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

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

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

<?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 VERSION "1.0">

<!ENTITY COMMANDNAME "password-prompt">

<!ENTITY TIMESTAMP "2008-08-31">

<title>&COMMANDNAME;</title>

<productname>&COMMANDNAME;</productname>

<title>Mandos Manual</title>

<productname>Mandos</productname>

<productnumber>&VERSION;</productnumber>

<date>&TIMESTAMP;</date>

<firstname>Björn</firstname>

</authorgroup>

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

<holder>Teddy Hogeborn</holder>

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

</copyright>

<para>

either version 3 of the License, or (at your option) any

later version.

</para>

<para>

This manual page is distributed in the hope that it will

be useful, but WITHOUT ANY WARRANTY; without even the

PARTICULAR PURPOSE. See the GNU General Public License

for more details.

</para>

<para>

You should have received a copy of the GNU General Public

License along with this program; If not, see

</para>

</legalnotice>

</refentryinfo>

<refentrytitle>&COMMANDNAME;</refentrytitle>

<manvolnum>8mandos</manvolnum>

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

Passprompt for luks during boot sequence

</refpurpose>

<refpurpose>Prompt for a password and output it.</refpurpose>

</refnamediv>

<command>&COMMANDNAME;</command>

<arg choice='opt'>--prefix<arg choice='plain'>PREFIX</arg></arg>

<arg choice='opt'>--debug</arg>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

<arg choice='plain'>--usage</arg>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

<arg choice='plain'>--version</arg>

</cmdsynopsis>

<arg choice="plain"><option>--prefix <replaceable

>PREFIX</replaceable></option></arg>

<arg choice="plain"><option>-p </option><replaceable

>PREFIX</replaceable></arg>

</group>

<sbr/>

<arg choice="opt"><option>--debug</option></arg>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

</group>

</cmdsynopsis>

<command>&COMMANDNAME;</command>

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

</cmdsynopsis>

<command>&COMMANDNAME;</command>

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

100

</group>

101

</cmdsynopsis>

102

</refsynopsisdiv>

103

104

105

<title>DESCRIPTION</title>

106

<para>

<command>&COMMANDNAME;</command> is a terminal program that ask for

passwords during boot sequence. It is a plugin to

<firstterm>mandos</firstterm>, and is used as a fallback and

alternative to retriving passwords from a mandos server. During

100

boot sequence the user is prompted for the disk password, and

101

when a password is given it then gets forwarded to

102

<acronym>LUKS</acronym>.

103

</para>

104

105

106

107

<term><literal>-p</literal>, <literal>--prefix=<replaceable>PREFIX

108

</replaceable></literal></term>

109

110

<para>

111

Prefix used before the passprompt

112

</para>

113

</listitem>

114

</varlistentry>

115

116

117

<term><literal>--debug</literal></term>

118

119

<para>

120

Debug mode

121

</para>

122

</listitem>

123

</varlistentry>

124

125

126

127

128

<para>

129

Gives a help message

130

</para>

131

</listitem>

132

</varlistentry>

133

134

135

<term><literal>--usage</literal></term>

136

137

<para>

138

Gives a short usage message

139

</para>

140

</listitem>

141

</varlistentry>

142

143

144

<term><literal>-V</literal>, <literal>--version</literal></term>

145

146

<para>

147

Prints the program version

148

</para>

149

</listitem>

150

</varlistentry>

151

</variablelist>

107

All <command>&COMMANDNAME;</command> does is prompt for a

108

password and output any given password to standard output. This

109

is not very useful on its own. This program is really meant to

110

run as a plugin in the <application>Mandos</application>

111

client-side system, where it is used as a fallback and

112

alternative to retriving passwords from a <application

113

>Mandos</application> server.

114

</para>

115

<para>

116

This program is little more than a <citerefentry><refentrytitle

117

>getpass</refentrytitle><manvolnum>3</manvolnum></citerefentry>

118

wrapper, although actual use of that function is not guaranteed

119

or implied.

120

</para>

121

</refsect1>

122

123

124

<title>OPTIONS</title>

125

<para>

126

This program is commonly not invoked from the command line; it

127

is normally started by the <application>Mandos</application>

128

plugin runner, see <citerefentry><refentrytitle

129

>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>

130

</citerefentry>. Any command line options this program accepts

131

are therefore normally provided by the plugin runner, and not

132

directly.

133

</para>

134

135

136

137

<term><option>--prefix=<replaceable

138

>PREFIX</replaceable></option></term>

139

<term><option>-p

140

<replaceable>PREFIX</replaceable></option></term>

141

142

<para>

143

Prefix string shown before the password prompt.

144

</para>

145

</listitem>

146

</varlistentry>

147

148

149

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

150

151

<para>

152

Enable debug mode. This will enable a lot of output to

153

standard error about what the program is doing. The

154

program will still perform all other functions normally.

155

</para>

156

</listitem>

157

</varlistentry>

158

159

160

161

162

163

<para>

164

Gives a help message about options and their meanings.

165

</para>

166

</listitem>

167

</varlistentry>

168

169

170

<term><option>--usage</option></term>

171

172

<para>

173

Gives a short usage message.

174

</para>

175

</listitem>

176

</varlistentry>

177

178

179

<term><option>--version</option></term>

180

181

182

<para>

183

Prints the program version.

184

</para>

185

</listitem>

186

</varlistentry>

187

</variablelist>

188

</refsect1>

189

190

191

<title>EXIT STATUS</title>

192

<para>

193

If exit status is 0, the output from the program is the password

194

as it was read. Otherwise, if exit status is other than 0, the

195

program has encountered an error, and any output so far could be

196

corrupt and/or truncated, and should therefore be ignored.

197

</para>

198

</refsect1>

199

200

201

<title>ENVIRONMENT</title>

202

203

204

<term><envar>cryptsource</envar></term>

205

<term><envar>crypttarget</envar></term>

206

207

<para>

208

If set, these environment variables will be assumed to

209

contain the source device name and the target device

210

mapper name, respectively, and will be shown as part of

211

the prompt.

212

</para>

213

<para>

214

These variables will normally be inherited from

215

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

216

<manvolnum>8mandos</manvolnum></citerefentry>, which will

217

normally have inherited them from

218

<filename>/scripts/local-top/cryptroot</filename> in the

219

initial RAM disk environment, which will have set them from

220

parsing kernel arguments and

221

<filename>/conf/conf.d/cryptroot</filename> (also in the

222

initial RAM disk environment), which in turn will have been

223

created when the initial RAM disk image was created by

224

<filename

225

>/usr/share/initramfs-tools/hooks/cryptroot</filename>, by

226

extracting the information of the root file system from

227

<filename >/etc/crypttab</filename>.

228

</para>

229

<para>

230

This behavior is meant to exactly mirror the behavior of

231

<command>askpass</command>, the default password prompter.

232

</para>

233

</listitem>

234

</varlistentry>

235

</variablelist>

236

</refsect1>

237

238

239

240

<para>

241

None are known at this time.

242

</para>

243

</refsect1>

244

245

246

<title>EXAMPLE</title>

247

<para>

248

Note that normally, command line options will not be given

249

directly, but via options for the Mandos <citerefentry

250

><refentrytitle>plugin-runner</refentrytitle>

251

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

252

</para>

253

254

<para>

255

Normal invocation needs no options:

256

</para>

257

<para>

258

<userinput>&COMMANDNAME;</userinput>

259

</para>

260

</informalexample>

261

262

<para>

263

Show a prefix before the prompt; in this case, a host name.

264

It might be useful to be reminded of which host needs a

265

password, in case of KVM switches, etc.

266

</para>

267

<para>

268

269

270

<userinput>&COMMANDNAME; --prefix=host.example.org:</userinput>

271

272

</para>

273

</informalexample>

274

275

<para>

276

Run in debug mode.

277

</para>

278

<para>

279

280

<userinput>&COMMANDNAME; --debug</userinput>

281

</para>

282

</informalexample>

283

</refsect1>

284

285

286

<title>SECURITY</title>

287

<para>

288

On its own, this program is very simple, and does not exactly

289

present any security risks. The one thing that could be

290

considered worthy of note is this: This program is meant to be

291

run by <citerefentry><refentrytitle

292

>plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>

293

</citerefentry>, and will, when run standalone, outside, in a

294

normal environment, immediately output on its standard output

295

any presumably secret password it just recieved. Therefore,

296

when running this program standalone (which should never

297

normally be done), take care not to type in any real secret

298

password by force of habit, since it would then immediately be

299

shown as output.

300

</para>

301

<para>

302

To further alleviate any risk of being locked out of a system,

303

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

304

<manvolnum>8mandos</manvolnum></citerefentry> has a fallback

305

mode which does the same thing as this program, only with less

306

features.

307

</para>

308

</refsect1>

309

310

311

312

<para>

313

<citerefentry><refentrytitle>crypttab</refentrytitle>

314

315

<citerefentry><refentrytitle>password-request</refentrytitle>

316

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

317

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

318

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

319

</para>

152

320

</refsect1>

153

321

</refentry>

322

323

324

325

326

Older »