Commit 528f7dc9 authored by Alex Tayts's avatar Alex Tayts
Browse files

Update README.md

parent 85bd3ed2
Wallet Module
=============
The module installs `wallet-client` package and provides a `wallet` resource to download any type of wallet object and keep a local copy up-to-date.
The module installs `wallet-client` package and provides a `wallet` resource to
download any type of wallet object and keep a local copy up-to-date.
## Wallet installation
......@@ -8,7 +9,8 @@ To install wallet client using the module just add
include wallet
to the manifest. The class installs the necessary prerequisites like wallet-client package and kerberos, if it has not been installed already.
to the manifest. The class installs the necessary prerequisites like wallet-client
package and kerberos, if it has not been installed already.
## Dependencies
......@@ -28,7 +30,8 @@ A name of an object in wallet. _Required_.
#### ensure
Can be `present` or `absent`, downloading an object from wallet or removing its local copy. Optional, defaults to _present_.
Can be `present` or `absent`, downloading an object from wallet or removing its
local copy. Optional, defaults to _present_.
#### path
......@@ -36,26 +39,38 @@ The name of a file for a downloaded wallet object. _Required_.
#### type
A type of a wallet object like `file`, `keytab` or `pam-duo`. Optional, defaults to _keytab_.
A type of a wallet object like `file`, `keytab` or `pam-duo`. Optional, defaults
to _keytab_.
#### auth_principal
A kerberos principal used for authentication to wallet, by default a server's host principal. Optional, defaults to a first entry in a keytab.
A kerberos principal used for authentication to wallet, by default a server's
host principal. Optional, defaults to a first entry in a keytab.
#### auth_keytab
A keytab file where `auth_principal` keys are stored. Must be an absolute path. Optional, defaults to _/etc/krb5.keytab_.
A keytab file where `auth_principal` keys are stored. Must be an absolute path.
Optional, defaults to _/etc/krb5.keytab_.
#### owner
A desired owner of a file created out of a wallet object. Can be given as a numeric _uid_ (like _1001_), string representation of a numeric _uid_ (like _"1001"_) or a user name (like _jdoe_). Optional, defaults to not setting an owner. Since typically puppet runs as root, that would be a default owner of a file.
A desired owner of a file created out of a wallet object. Can be given as a numeric
_uid_ (like _1001_), string representation of a numeric _uid_ (like _"1001"_) or
a user name (like _jdoe_). Optional, defaults to not setting an owner.
Since typically puppet runs as root, that would be a default owner of a file.
#### group
A desired group of a file created out of a wallet object. Can be given as a numeric _gid_ (like _1001_), string representation of a numeric _gid_ (like _"1001"_) or a group name (like _operator_). Optional, defaults to not setting a group. Since typically puppet runs as root, that would be a default group of a file.
A desired group of a file created out of a wallet object. Can be given as a numeric
_gid_ (like _1001_), string representation of a numeric _gid_ (like _"1001"_) or
a group name (like _operator_). Optional, defaults to not setting a group. Since
typically puppet runs as root, that would be a default group of a file.
#### mode
A desired mode of a file created out of a wallet object. Can be given as a numeric _uid_ (like _1001_) or a string representation of a numeric _uid_ (like _"1001"_). Optional, defaults to not setting a mode. Wallet client automatically sets mode to 600, which would be a natural default.
A desired mode of a file created out of a wallet object. Can be given as a numeric
_mode_ (like _600_) or a string representation of a numeric _mode_ (like _"600"_).
Optional, defaults to not setting a mode. Wallet client automatically sets mode
to 600, which would be a natural default.
#### heimdal
......@@ -63,13 +78,19 @@ Kerberos distribution, Heimdal if true, otherwise MIT. Optional, defaults to _fa
#### verify
A boolean enabling or disabling verification of a local copy of a wallet object. If verification fails for any reason (file is missing, modified, stale keytab, etc.), it is downloaded from wallet again. Optional, defaults to _false_.
A boolean enabling or disabling verification of a local copy of a wallet object.
If verification fails for any reason (file is missing, modified, stale keytab,
etc.), it is downloaded from wallet again. Optional, defaults to _false_.
## Examples
### Download and maintain a keytab
A keytab wallet object `service/myapplication` is downloaded and stored in a file. Host principal in a host keytab is used to authenticate to wallet. Ownership is set to allow access by _myapp_ account. Keytab is verified on every puppet run to contain the keys of a `service/myapplication` principal. If keys are updated in wallet, the local keytab would also be updated with them.
A keytab wallet object `service/myapplication` is downloaded and stored in a file.
Host principal in a host keytab is used to authenticate to wallet. Ownership is
set to allow access by _myapp_ account. Keytab is verified on every puppet run to
contain the keys of a `service/myapplication` principal. If keys are updated in
wallet, the local keytab would also be updated with them.
```
wallet { 'service/myapplication':
......@@ -83,7 +104,11 @@ wallet { 'service/myapplication':
}
```
The same, except a particular key from a host keytab is used to authenticate to wallet and keytab is not maintained. It is only checked for a presence of a key without worrying about its validity. If keytab is misssing, it would be recreated from a wallet item. If a key for a `service/myapplication` principal is missing from a keytab, it would be added.
The same, except a particular key from a host keytab is used to authenticate to
wallet and keytab is not maintained. It is only checked for a presence of a key
without worrying about its validity. If keytab is misssing, it would be recreated
from a wallet item. If a key for a `service/myapplication` principal is missing
from a keytab, it would be added.
```
wallet { 'service/myapplication':
......@@ -97,7 +122,10 @@ wallet { 'service/myapplication':
### Download and maintain a file
A file with a shibboleth key stored in wallet is downloaded. Host principal found in a host keytab is used to authenticate to wallet. The content of a shibboleth key is maintained. If it gets updated in wallet, a local copy would get updated as well.
A file with a shibboleth key stored in wallet is downloaded. Host principal found
in a host keytab is used to authenticate to wallet. The content of a shibboleth
key is maintained. If it gets updated in wallet, a local copy would get updated
as well.
```
wallet { 'ssl-keypair/server.stanford.edu/shibboleth':
......@@ -110,7 +138,10 @@ wallet { 'ssl-keypair/server.stanford.edu/shibboleth':
### Get Duo configuration for a server
A duo configuration is downloaded in a local file. Host principal found in a host keytab is used to authenticate to wallet. The content of a duo configuration is not maintained. If a configuration file gets missing it would be downloaded again, but local modifictaions of its content won't be overwritten.
A duo configuration is downloaded in a local file. Host principal found in a host
keytab is used to authenticate to wallet. The content of a duo configuration is
not maintained. If a configuration file gets missing it would be downloaded again,
but local modifictaions of its content won't be overwritten.
```
wallet { 'server.stanford.edu':
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment