lustre/doc/lgss_sk.8

   1 .TH lgss_sk 8 "2016 Jan 12" Lustre "configuration utilities"
   2 .SH NAME
   3 lgss_sk \- Lustre GSS Shared-Key tool
   4 .SH SYNOPSIS
   5 .B "lgss_sk [OPTIONS] -r <keyfile> | -w <keyfile> | -m <keyfile> | -l <keyfile>"
   6 .br
   7 .SH DESCRIPTION
   8 .B lgss_sk
   9 can be used to read, write, modify, and load the contents of a shared-key keyfile.
  10 .SH OPTIONS
  11 .B lgss_sk
  12 accepts the following options:
  13 .TP
  14 .I "-l, --load <keyfile>"
  15 Load key from file into user's session keyring.
  16 .TP
  17 .I "-m, --modify <keyfile>"
  18 Modify a file's key attributes.
  19 .TP
  20 .I "-r, --read <keyfile>"
  21 Show file's key attributes.
  22 .TP
  23 .I "-w, --write <keyfile>"
  24 Generate key file.
  25 .HP
  26 Modify/Write Options:
  27 .TP
  28 .I "-c, --crypt <num>"
  29 Cipher for encryption (Default: AES-256-CTR)
  30 .RS
  31 AES-256-CTR
  32 .RE
  33 .TP
  34 .I "-i, --hmac <num>"
  35 Hash algorithm for integrity (Default: SHA256)
  36 .RS
  37 SHA256
  38 .br
  39 SHA512
  40 .RE
  41 .TP
  42 .I "-e, --expire <num>"
  43 Seconds before contexts from key expire (Default: 604800 seconds).
  44 .TP
  45 .I "-f, --fsname <name>"
  46 File system name for key.
  47 .TP
  48 .I "-g, --mgsnids <nids>"
  49 Comma seperated list of MGS NIDs.  Only required when mgssec is used (Default: "").
  50 .TP
  51 .I "-n, --nodemap <name>"
  52 Nodemap name for key (Default: "default").
  53 .TP
  54 .I "-p, --prime-bits <len>"
  55 Length of prime (p) in bits used for the DHKE (Default: 2048).  This is
  56 generated only for client keys and can take a while to generate.  For server
  57 and MGS keys this value also sets the minimum acceptable prime length from a
  58 client.  If a client attempts to connect with a smaller prime it will reject
  59 the connection.  In this way servers can "guarantee" the minimum encryption
  60 level acceptable.
  61 .TP
  62 .I "-t, --type <type>"
  63 The type is a mandatory parameter for writing a key and optional for modifying.
  64 Valid key types:
  65 .nf
  66 mgs    - is used for the MGS where --mgssec is used
  67 server - for MDS or OSS servers
  68 client - For clients as well as servers who communicate with other servers in a
  69          client context (e.g. MDS communication with OSTs)
  70 .fi
  71 .TP
  72 .I "-k, --shared <len>"
  73 Shared key length in bits (Default: 256).
  74 .TP
  75 .I "-d, --data <file>"
  76 Shared key entopy data source (default: /dev/random).  It is possible to
  77 use /dev/urandom for testing, but this may provide less security in some
  78 cases.  You may need to press keys on the keyboard or move the mouse
  79 (if directly attached to the system) or cause disk IO (if system is remote),
  80 in order to generate entropy for the key if there is not a hardware random
  81 number generator on the system.
  82 .HP
  83 Other Options:
  84 .TP
  85 .I "-v, --verbose"
  86 Increase verbosity for errors.
  87 .SH NOTES
  88 The key file is generally the same for client and servers with a few exceptions:
  89 .IP
  90 .nf
  91 1. Types can differ
  92 2. Both have the prime length but only client keys will have the actual prime
  93    value populated.
  94 .fi
  95 .LP
  96 Therefore a
  97 .B server
  98 or
  99 .B mgs
 100 key can be distributed to a client but the clients
 101 must change the type to generate a prime.
 102 .HP
 103 .SH EXAMPLES
 104 Create a key for file system
 105 .B tank
 106 for nodemap
 107 .B biology
 108 with type server.
 109 Once on the client the file should be modified to reflect that it is of type
 110 .B client
 111 and will also generate a prime for the key.
 112 .IP
 113 .nf
 114 [root@server ~]# lgss_sk -f tank -n biology -t server -w tank.server.biology.key
 115 [root@server ~]# scp tank.server.biology.key user@client:tank.client.biology.key
 116
 117 [root@client ~]# lgss_sk -t client -m tank.client.biology.key
 118 .fi
 119 .LP
 120 Add MGS NIDs to existing key:
 121 .IP
 122 .nf
 123 [root@server ~]# lgss_sk -g 192.168.1.101@tcp,10.10.0.101@o2ib \\
 124 -m tank.server.biology.key
 125
 126 [root@client ~]# lgss_sk -g 192.168.1.101@tcp,10.10.0.101@o2ib \\
 127 -m tank.client.biology.key
 128 .fi
 129 .LP
 130 Show key attributes:
 131 .IP
 132 .nf
 133 [root@server ~]# lgss_sk -r tank.server.biology.key
 134 Version:        1
 135 Type:           server
 136 HMAC alg:       SHA256
 137 Crypt alg:      AES-256-CTR
 138 Ctx Expiration: 604800 seconds
 139 Shared keylen:  256 bits
 140 Prime length:   2048 bits
 141 File system:    tank
 142 MGS NIDs:       192.168.1.101@tcp 10.10.0.101@o2ib
 143 Nodemap name:   biology
 144 Shared key:
 145   0000: c160 00c6 e5ba 11df 50cb c420 ae61 c1b3  .`......P.. .a..
 146   0010: c76e 5a82 ce48 fde9 d319 ce26 cfc4 b91e  .nZ..H.....&....
 147 Prime (p) :
 148
 149 [root@client ~]# lgss_sk -r tank.client.biology.key
 150 Version:        1
 151 Type:           client
 152 HMAC alg:       SHA256
 153 Crypt alg:      AES-256-CTR
 154 Ctx Expiration: 604800 seconds
 155 Shared keylen:  256 bits
 156 Prime length:   2048 bits
 157 File system:    tank
 158 MGS NIDs:       192.168.1.101@tcp 10.10.0.101@o2ib
 159 Nodemap name:   biology
 160 Shared key:
 161   0000: c160 00c6 e5ba 11df 50cb c420 ae61 c1b3  .`......P.. .a..
 162   0010: c76e 5a82 ce48 fde9 d319 ce26 cfc4 b91e  .nZ..H.....&....
 163 Prime (p) :
 164   0000: be19 9412 a4c5 3355 9963 ebdf 3fce a5d8  ......3U.c..?...
 165   0010: 9776 50db 70b1 1ad4 a22b 3b68 2ae6 fb7a  .vP.p....+;h*..z
 166   0020: 803b 2f67 e6ee cd55 3df1 afbd 4e3a b620  .;/g...U=...N:.
 167   0030: 1d86 4182 bb03 d9b5 9605 658e 4dfb 6d39  ..A.......e.M.m9
 168   0040: 0394 b789 437f d30b 3fc0 2c7f 42bb 1987  ....C...?.,.B...
 169   0050: 0837 bae1 5332 4992 3a0c 9d01 d350 c2bb  .7..S2I.:....P..
 170   0060: ed25 27e9 5439 f295 4c04 08cd bcfe 7e0b  .%'.T9..L.....~.
 171   0070: 542b e80b 2fb5 eed0 9ca8 f9bc a792 baf1  T+../...........
 172   0080: db1a af08 cee7 7b7f f3e4 7f14 71ca b7c9  ......{.....q...
 173   0090: 9d07 c24b 8f04 65e3 4c8c fdd5 6e70 641d  ...K..e.L...npd.
 174   00a0: af24 a48a b1c7 d2ff 9fee 158e 7025 6d81  .$..........p%m.
 175   00b0: a54f 48f9 712f cac3 28fb 426c 330b 07ff  .OH.q/..(.Bl3...
 176   00c0: c4a4 cb67 a46b cc57 1846 dc9d 4ce4 fa65  ...g.k.W.F..L..e
 177   00d0: 7fc6 e77d 1220 b807 6c7c 5660 b703 39d2  ...}. ..l|V`..9.
 178   00e0: 1d99 bd89 e2f1 3e40 74a1 709c 6e6c 6624  ......>@t.p.nlf$
 179   00f0: fad6 97bf c3e0 b0d4 cefc 3596 dd69 5223  ..........5..iR#
 180
 181 .fi
 182 .br
 183 .SH "SEE ALSO"
 184 .BR nids (5)