doc/pwmc.1.in

   1 .\" This program is free software; you can redistribute it and/or modify
   2 .\" it under the terms of the GNU General Public License as published by
   3 .\" the Free Software Foundation; either version 2 of the License, or
   4 .\" (at your option) any later version.
   5 .\"
   6 .\" This program is distributed in the hope that it will be useful,
   7 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
   8 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   9 .\" GNU General Public License for more details.
  10 .\"
  11 .\" You should have received a copy of the GNU General Public License
  12 .\" along with this program; if not, write to the Free Software
  13 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  14 .de URL
  15 \\$2 \(laURL: \\$1 \(ra\\$3
  16 ..
  17 .if \n[.g] .mso www.tmac
  18 .TH PWMD 1 "04 Apr 2009" "Password Manager Client" "Password Manager Client"
  19 .SH NAME
  20
  21 pwmc \- send a command to a pwmd server
  22 .SH SYNOPSIS
  23 .B pwmc
  24 [options] [file]
  25
  26 .SH DESCRIPTION
  27 .B pwmc
  28 is a
  29 .BR libpwmd (3)
  30 client for
  31 .BR pwmd (1) .
  32 A server command is read from standard input and the command result, if any,
  33 is sent to either a file descriptor or standard output.
  34
  35 .SH OPTIONS
  36 .TP
  37 .I "\--url <string>"
  38 A string to parse that can be used for remote pwmd server details rather than
  39 the other command line options.
  40 See
  41 .B EXAMPLES .
  42
  43 .TP
  44 .I "\--socket <path>"
  45 Connect to the specified local UNIX domain socket.  The default is
  46 \fB~/.pwmd/socket\fR.
  47
  48 .TP
  49 .I "\--host, -h <hostname>"
  50 Establish an SSH connection to the specified hostname. See
  51 .B SSH
  52 below for how to setup the SSH host to use
  53 .BR pwmd (1)
  54 via a proxy.
  55
  56 .TP
  57 .I "\--port, -p <port>"
  58 The port of the hostname to connect to. The default is 22.
  59
  60 .TP
  61 .I "\--known-hosts, -k <filename>"
  62 A file containing a list of SHA1 fingerprints of remote SSH servers that
  63 .BR libpwmd (3)
  64 will check against while authenticating the remote host. Note that this file
  65 format differs from the usual
  66 .BR ssh (1)
  67 known_hosts file format.
  68
  69 .TP
  70 .I "\--identity, -i <filename>"
  71 The
  72 .BR ssh (1)
  73 identity file to use for public key authentication. This is the only supported
  74 method of SSH authentication. Both the public and private key must be
  75 available.
  76
  77 .TP
  78 .I "\--user, -u <username>"
  79 The username to login as on the remote SSH server. The default is the invoking
  80 user.
  81
  82 .TP
  83 .I "\--get-hostkey, -g"
  84 Retrieve the SHA1 fingerprint of the remote SSH hostname specified with
  85 .B -h .
  86 The result should be appended to the known hosts file.
  87
  88 .TP
  89 .I "\--ipv4, -4"
  90 Connect to an IPv4 host only. The default is to try an IPv6 host first, then
  91 an IPv4 host.
  92
  93 .TP
  94 .I "\--ipv4, -6"
  95 Connect to an IPv6 host only. The default is to try an IPv6 host first, then
  96 an IPv4 host.
  97
  98 .TP
  99 .I "\--name, -n <string>"
 100 Set the client name to the specified string. This string is what shows up in
 101 the
 102 .BR pwmd (1)
 103 log files. The default is "pwmc".
 104
 105 .TP
 106 .I "\--no-status"
 107 Don't show server status messages. By default, status messages are written to
 108 stderr.
 109
 110 .TP
 111 .I "\--inquire-fd <FD>"
 112 For commands that use an INQUIRE from the server (STORE and IMPORT), this sets
 113 the file descriptor that the data will be read from. By default, stdin is
 114 used.
 115
 116 .TP
 117 .I "\--output-fd <FD>"
 118 Redirect output to the specified file descriptor. The default is stdout.
 119
 120 .TP
 121 .I "\--save, -S"
 122 After the command has been processed and no error occurred, send the SAVE
 123 command to the server.
 124
 125 .TP
 126 .I "\--iterations, -I <integer>"
 127 Specifies the number of encryption iterations to use when
 128 .B -S
 129 is used. The default is specified in the
 130 .BR pwmd (1)
 131 server configuration.
 132
 133 .TP
 134 .I "\--passphrase, -P <string>"
 135 The passphrase to use when required. If not set then a
 136 .BR pinentry (1)
 137 will be used if available.
 138
 139 .TP
 140 .I "\--pinentry, <path>"
 141 The full path to the pinentry binary. The default is the
 142 .BR pwmd (1)
 143 server configured setting.
 144
 145 .TP
 146 .I "\--ttyname, <path>"
 147 The full path of the TTY for
 148 .BR pinentry (1)
 149 to prompt on. The default is the current terminal.
 150
 151 .TP
 152 .I "\--ttytype, <string>"
 153 The terminal type of the specified TTY that
 154 .BR pinentry (1)
 155 should use. This is required if
 156 .B --ttyname
 157 is specified.
 158
 159 .TP
 160 .I "\--display, <string>"
 161 The X11 display that
 162 .BR pinentry (1)
 163 should use. Note that a remote SSH
 164 .BR pinentry (1)
 165 is currently not supported. The default is the current DISPLAY if set.
 166
 167 .TP
 168 .I "\--lc-ctype, <string>"
 169 For
 170 .BR pinentry (1)
 171 localization.
 172
 173 .TP
 174 .I "\--lc-messages, <string>"
 175 For
 176 .BR pinentry (1)
 177 localization.
 178
 179 .TP
 180 .I "\--tries, <N>"
 181 The number of times before failing when an invalid passphrase is entered in
 182 the
 183 .BR pinentry (1)
 184 dialog. The default is 3.
 185
 186 .TP
 187 .I "\--timeout, <seconds>"
 188 The number of seconds before
 189 .BR pinentry (1)
 190 will timeout while waiting for a passphrase. The default is 30.
 191
 192 .TP
 193 .I "\--version"
 194 Version information.
 195 .TP
 196 .I "\--help"
 197 Help text.
 198
 199
 200 .SH SSH
 201 In order to get this to work you need to put the following in your
 202 .B ~/.ssh/authorized_keys
 203 file on the remote SSH host. It should be prepended to the hash of the public
 204 key that was generated using
 205 .BR ssh-keygen (1)
 206 and specified using the
 207 .B --identity
 208 command line option:
 209
 210     command="socat gopen:$HOME/.pwmd/socket -"
 211
 212 The
 213 .BR socat (1)
 214 command can be replaced with any utility that can read from stdin and write
 215 to a unix domain socket, and vice-versa.
 216
 217
 218 .SH PINENTRY
 219 .BR pinentry (1)
 220 is a program that prompts the user for input of a passphrase. This is
 221 currently not supported when connected to a remote pwmd server since X11 port
 222 forwarding is not done yet.
 223
 224 The terminal, terminal type or DISPLAY that pinentry will prompt on is either
 225 set with the command line options or uses options set in
 226 .B ~/.pwmd/pinentry.conf
 227 when available. Otherwise the current terminal and terminal type or X11
 228 DISPLAY is used.
 229
 230 The
 231 .B ~/.pwmd/pinentry.conf
 232 file contains one NAME=VALUE pair per line. Comments begin with a '#'.
 233
 234 .B PATH
 235 The full path to the location of the pinentry binary.
 236
 237 .B DISPLAY
 238 The X11 display to use.
 239
 240 .B TTYNAME
 241 The full path to the tty that pinentry should prompt on.
 242
 243 .B TTYTYPE
 244 The terminal type of the tty (i.e., vt100) which is required if DISPLAY is not
 245 set.
 246
 247
 248 .SH EXAMPLES
 249 To list the available accounts and use
 250 .BR pinentry (1)
 251 to get the passphrase (if required):
 252 .RS
 253 echo list | pwmc filename
 254 .RE
 255 .P
 256 To store an element path and save the file afterwards:
 257 .RS
 258 echo -ne 'store isp\\tsmtp\\thostname\\tsomehost.com' | pwmc -S filename
 259 .RE
 260 .P
 261 Store a large file:
 262 .RS
 263 echo -en 'store blah\\tstuff\\t' | pwmc -S -I 3 filename 3<data_file
 264 .P
 265 And then to get the content:
 266 .P
 267 echo -e 'get blah\\tstuff' | pwmc filename
 268 .RE
 269 .P
 270 Clear the file cache for a single file:
 271 .RS
 272 echo 'clearcache filename' | pwmc
 273 .RE
 274 .P
 275 To list the contents of a data file which is stored on a  remote pwmd server
 276 over an SSH connection:
 277 .RS
 278 echo list | pwmc --url ssh://user@hostname,~/identity,~/known_hosts filename
 279 .RE
 280
 281 .SH FILES
 282 .TP
 283 .B ~/.pwmd/socket
 284 Default socket to connect to.
 285 .TP
 286 .B ~/.pwmd/pinentry.conf
 287 Default settings that
 288 .BR pinentry (1)
 289 will use for the terminal, terminal type or X11 display.
 290 .TP
 291 .B @pinentry@
 292 Default location of the
 293 .BR pinentry (1)
 294 binary.
 295
 296 .SH AUTHOR
 297 Ben Kibbey <bjk@luxsci.net>
 298 .br
 299 .URL "http://bjk.sourceforge.net/pwmd/" "PWMD Homepage" .
 300
 301 .SH "SEE ALSO"
 302 .BR pwmd (1),
 303 .BR pinentry (1),
 304 .BR ssh-keygen (1),
 305 .BR authorized_keys (5),
 306 .BR socat (1),
 307 .BR libpwmd (3)