{"id":15517044,"url":"https://github.com/deric/puppet-accounts","last_synced_at":"2025-05-08T21:34:55.477Z","repository":{"id":13538010,"uuid":"16229660","full_name":"deric/puppet-accounts","owner":"deric","description":"Simple hierachical management of Linux user accounts, groups and SSH keys","archived":false,"fork":false,"pushed_at":"2020-02-28T13:33:00.000Z","size":425,"stargazers_count":33,"open_issues_count":19,"forks_count":34,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-22T00:03:20.041Z","etag":null,"topics":["account-management","accounts","groups","hiera","passwd","puppet","users"],"latest_commit_sha":null,"homepage":"https://forge.puppetlabs.com/deric/accounts","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"cornflourblue/angular-registration-login-example","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deric.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-25T11:24:41.000Z","updated_at":"2025-03-06T05:43:09.000Z","dependencies_parsed_at":"2022-07-30T15:07:59.970Z","dependency_job_id":null,"html_url":"https://github.com/deric/puppet-accounts","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deric%2Fpuppet-accounts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deric%2Fpuppet-accounts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deric%2Fpuppet-accounts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deric%2Fpuppet-accounts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deric","download_url":"https://codeload.github.com/deric/puppet-accounts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253153163,"owners_count":21862318,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["account-management","accounts","groups","hiera","passwd","puppet","users"],"created_at":"2024-10-02T10:11:01.597Z","updated_at":"2025-05-08T21:34:55.443Z","avatar_url":"https://github.com/deric.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Puppet Accounts Management\n\n[![Puppet\nForge](http://img.shields.io/puppetforge/v/deric/accounts.svg)](https://forge.puppetlabs.com/deric/accounts) [![Build Status](https://travis-ci.org/deric/puppet-accounts.png?branch=master)](https://travis-ci.org/deric/puppet-accounts) [![Puppet Forge\nDownloads](http://img.shields.io/puppetforge/dt/deric/accounts.svg)](https://forge.puppetlabs.com/deric/accounts/scores)\n\nThis is puppet module for managing user accounts, groups and setting ssh keys.\n\nVersion compatibility:\n\n| `deric-accounts`  | Puppet 3.x    | Puppet 4.x   | Puppet 5.x | Puppet 6.x |\n| ----------------- | ------------- |--------------| -----------|------------|\n| `1.5.x`           | :heavy_check_mark: | :heavy_check_mark: | :question: | :x:  |\n| `2.0.x`           | :question:  | :heavy_check_mark: |  :heavy_check_mark: | :x:  |\n| `2.1.x`           | :question: | :question: | :heavy_check_mark: | :heavy_check_mark: |\n\n  * `deric-acounts \u003e= 2.0` - Puppet 4.x, Puppet 5.x\n  * `deric-acounts \u003c 2.0` - Puppet 3.x, Puppet 4.x\n\nOrigin: https://github.com/deric/puppet-accounts\n\nBasic usage:\n\n```puppet\nclass {'::accounts':}\n```\n\nor with pure YAML declaration make sure to use the `hiera_include` function e.g. in `site.pp` (see [Hiera docs for details](https://docs.puppet.com/hiera/3.2/complete_example.html#using-hierainclude)):\n```puppet\nlookup('classes', {merge =\u003e unique}).include\n```\nand all other definition can be in YAML hierarchy:\n```yaml\nclasses:\n  - '::accounts'\naccounts::users:\n  myuser:\n    groups: ['users']\n```\n\nHiera allows flexible account management, if you want to have a group defined on all nodes, just put in global hiera config, e.g. `common.yml`:\n\n```yaml\naccounts::user_defaults:\n  shell: '/bin/bash'\n  # will delete all authorized keys that are not in Puppet\n  purge_ssh_keys: true\naccounts::groups:\n  www-data:\n    gid: 33\n    # not necessarily complete list of memebers, you can assign users to the same group on\n    # user's level using `groups: ['www-data']`\n    members: ['john']\n```\n\nand user accounts:\n\n```yaml\naccounts::users:\n  john:\n    comment: \"John Doe\"\n    groups: [\"sudo\", \"users\"]\n    shell: \"/bin/bash\"\n    pwhash: \"$6$GDH43O5m$FaJsdjUta1wXcITgKekNGUIfrqxYogW\"\n    ssh_keys:\n      'john@doe': # an unique indentifier of a key\n        type: \"ssh-rsa\"\n        key: \"a valid public ssh key string\"\n  alice:\n    comment: \"Alice\"\n```\n\nFor more examples see [configuration used for tests](https://github.com/deric/puppet-accounts/blob/master/spec/fixtures/hiera/default.yaml).\n\n### Custom home\n\nWhen no `home` is specified directory will be created in `/home/{username}`.\n\n```yaml\n  alice:\n    comment: 'Alice'\n    home: '/var/alice'\n```\n\n### Group management\n\nBy default each user has a group with the same name. You can change this with `manage_group` parameter:\n\n```yaml\naccounts::users:\n john:\n   manage_group: false\n   groups:\n     - 'users'\n     - 'www-data'\n```\nOptionally you can assign user to other groups by supplying a `groups` array.\n\n### Primary group\n\nAccount's primary group can be configured using `primary_group` parameter:\n```yaml\naccounts::users:\n john:\n   # will create primary group `doe` instead of default `john` group\n   primary_group: 'doe'\n   manage_group: true\n   groups:\n     - 'sudo'\n```\nit can be defined numerically or as a group name. Setting [directly `gid`](https://docs.puppet.com/puppet/latest/reference/types/user.html#user-attribute-gid) parametr would have the same effect. Parameter `manage_group` is not considered when you set `gid`.\n\n### Account removal\n\nRemoving account could be done by setting `ensure` parameter to `absent`:\n\n```yaml\naccounts::users:\n john:\n   ensure: 'absent'\n   managehome: true\n```\n\nIf `managehome` is set to `true` (default), also home directory will be removed!\n\n### Root account\n\n`root` home is set to `/root` unless defined otherwise (using `home` parameter). You can supply multiple keys for one account.\n```yaml\naccounts::users:\n  root:\n    ssh_keys:\n      'mykey1':\n        type: 'ssh-rsa'\n        key: 'AAAA....'\n      'otherkey':\n        type: 'ssh-dsa'\n        key: 'AAAAB...'\n```\n\n### Additional SSH key options\n\nSSH allows providing many options regarding authorized keys, see [SSH documentation](http://man.openbsd.org/OpenBSD-current/man8/sshd.8#AUTHORIZED_KEYS_FILE_FORMAT) for complete specification.\n\nOptions should be passed as an array:\n```yaml\naccounts::users:\n  foo:\n    ssh_keys:\n      'mykey1':\n        type: 'ssh-rsa'\n        key: 'AAAA....'\n        options:\n          - 'permitopen=\"10.4.3.29:3306\"'\n          - 'permitopen=\"10.4.3.30:5432\"'\n          - 'no-port-forwarding'\n          - 'no-X11-forwarding'\n          - 'no-agent-forwarding'\n          - 'from=\"serverA,serverB\"'\n          - 'command=\"/path/to/script.sh arg1 $SSH_ORIGINAL_COMMAND\"'\n```\n\n### Password Management\n\nYou can either provide an already hashed password or you can let the module take\ncare of hashing.\n\nProviding hashed passwords from Hiera is secure by default. Please use something\nlike hiera-eyaml or hiera-gpg for cleartext passwords within Puppet.\n\nExample with pre-hashed password:\n```yaml\naccounts::users:\n  john:\n    pwhash: \"$6$GDH43O5m$FaJsdjUta1wXcITgKekNGUIfrqxYogW\"\n```\nExample with cleartext password, using hiera-eyaml:\n```yaml\naccounts::users:\n  john:\n    password: \u003e\n      ENC[PKCS7,MIIBeQYJKoZIhvcNAQcDoIIBajCCAWYCAQAxggEhMIIBHQIBADAFMAACAQAw\n      ...\n      1yv7gBCuc3T2xV9gPYe+DrALDYB+]\n   ensure: present\n```\nThe password hashing salt is generated with `fqdn_rand_string` from stdlib the first\ntime the user is created. After that, the salt is read by a custom fact and reused,\neven on password changes (which is ok, it's just a salt...). You may specify an\nexplicit salt if needed (see variable doc below).\n\n## User\n\n* `authorized_keys_file` - allows providing location of custom `authorized_keys`\n* `purge_ssh_keys` - delete all keys except those explicitly provided (default: `false`)\n* `ssh_key_source` - provide file with authorized keys\n* `pwhash` - set password hash\n* `password` - (optional) set cleartext password (mutually exclusive with `pwhash`!)\n* `salt` - (optional, default random/fact based) salt for hashing the `password`, this may only be up to 16 characters\n* `hash` - (optional, default 'SHA-512') password hash function to use (valid strings: see [puppetlabs/stdlib#pw_hash](https://github.com/puppetlabs/puppetlabs-stdlib#pw_hash))\n* `force_removal` - will kill user's process before removing account with `ensure =\u003e absent` (default: `true`)\n* `hushlogin` - creates a `.hushlogin` file in users home directory that disables the motd\n* `ssh_dir_owner` (default: `user`) owner of `.ssh` directory (and `authorized_keys` file in the directory). Should not be changed unless you're moving out of user's home (see #64 for more details).\n* ssh_dir_group` (default: `user`) owner of `.ssh` directory (and `authorized_keys` file in the directory).\n* `manage_ssh_dir` Whether `.ssh` directory should be managed by this module (default: `true`)\n\nExample:\n\n```yaml\naccounts::users:\n john:\n   authorized_keys_file: '/home/.ssh/auth_file'\n   managehome: true\n   purge_ssh_keys: false\n   pwhash: ''\n   hushlogin: true\n```\n\n### `umask`\n\nDefault permissions for creating new files are managed via `~/.bash_profile` and `~/.bashrc`.\n\n```yaml\naccounts::users:\n john:\n   manageumask: true\n   umask: '022'\n```\n\nBy default `umask` is not managed. Note that you can configure global `umask` for all users via `accounts::config` (see below).\n\n## Global settings\n\nYou can provide global defaults for all users:\n\n```yaml\naccounts::user_defaults:\n  shell: '/bin/dash'\n  groups: ['users']\n  hushlogin: true\n```\n * `groups` common group(s) for all users\n\nNote that configuration from Hiera gets merged to with Puppet code.\n\n### System-wide configuration\n\nGlobal settings affects also user accounts created outside of this module.\n\n```yaml\naccounts::config:\n  first_uid: 1000\n  last_uid: 99999\n  first_gid: 1000\n  last_gid: 99999\n  umask: '077'\n```\n * `first_uid` - Sets the lowest UID for non system users\n * `last_uid` - Sets the highest UID for non system users\n * `first_gid` - Sets the lowest GID for non system groups\n * `last_gid` - Sets the highest GID for non system groups\n * `umask` - Default global `umask` (can be overriden in user's `~/.profile`)\n\n\n### Populate home folder\n\nAllows fetching user's directory content from some storage:\n\n```yaml\naccounts::users:\n john:\n   populate_home: true\n   home_directory_contents: 'puppet:///modules/accounts'\n```\nwhich default to `puppet:///modules/accounts/{username}`.\n\n## Testing\n\nWhich accounts will be installed on specific machine can be checked from command line:\n\n```bash\n$ hiera -y my_node.yml accounts::users --hash\n```\n\nwhere `my_node.yml` is a file which you get from facter running at some node:\n\n```bash\n$ facter -y \u003e my_node.yml\n```\n\n### Without Hiera\n\nUsing Hiera is optional (though prefered option), you can configure accounts directly from Puppet code:\n\n\n```puppet\nclass {'accounts':\n  users =\u003e { 'john' =\u003e { 'comment' =\u003e 'John Doe' }}\n}\n```\n\nWhen defining adding a user to multiple groups, we have to ensure, that all the groups exists first:\n\n```puppet\n  class {'accounts':\n    groups =\u003e {\n      'users' =\u003e {\n        'gid' =\u003e 100,\n      },\n      'puppet' =\u003e {\n        'gid' =\u003e 111,\n      }\n    },\n    users =\u003e { 'john' =\u003e {\n      'shell'   =\u003e '/bin/bash',\n      'groups'  =\u003e ['users', 'puppet'],\n      'ssh_keys' =\u003e { 'johns_key' =\u003e {'type' =\u003e 'ssh-rsa', 'key' =\u003e 'public_ssh_key_xxx' }}\n    }}\n  }\n```\n\n## Puppet compatibility\n\nThis modules heavily relies on Hiera functionality, thus it's recommended to use at least Puppet 3. Puppet 2.7 might work with `hiera-puppet` gem, but we don't test this automatically, see [docs](https://docs.puppetlabs.com/hiera/1/installing.html#step-2-install-the-puppet-functions) for more details.\n\n  * `3.x` work out-of-the-box\n  * `4.x` other backends than Hiera might work\n\n## Hiera configuration\n\nPuppet 4.9 comes with Hiera 5 support. For earlier versions see Hiera 3 section.\n\n### Hiera 5\n\nWhen migrating from Hiera 3 see the [official guide](https://puppet.com/docs/puppet/5.0/hiera_migrate_v3_yaml.html):\n\n`hiera.yaml` has slightly different syntax:\n\n```yaml\n---\nversion: 5\ndefaults:  # Used for any hierarchy level that omits these keys.\n  datadir: hieradata         # This path is relative to hiera.yaml's directory.\n  data_hash: yaml_data  # Use the built-in YAML backend.\n\nhierarchy:\n  - name: \"Common\"\n    path: \"common.yaml\"\n\n```\nSupported [merge strategies](https://puppet.com/docs/puppet/5.0/hiera_merging.html) are:\n\n* `first` A first-found lookup doesn’t merge anything; it returns the first value found, and ignores the rest (default).\n* `unique` A unique merge (sometimes called “array merge”) combines any number of array and scalar (string/number/boolean) values to return a merged, flattened array with all duplicate values removed.\n* `hash` A hash merge combines the keys and values of any number of hashes to return a merged hash.\n* `deep` Like a hash merge, a deep merge combines the keys and values of any number of hashes to return a merged hash. But if the same key exists in multiple source hashes, Hiera recursively merges them.\n\n\nUsing `lookup_options` you can define rules to use strategy that suits your needs.\n```yaml\n---\nlookup_options:\n  \"^accounts::(.*)\":\n    merge:\n      strategy: deep\n      # sort_merged_arrays: false\n      # merge_hash_arrays: false\n```\n\n### Hiera 3\n\nFor more complex hierarchies (defined in multiple files) `deep_merge` gem is needed, see [Hiera docs](https://docs.puppetlabs.com/hiera/3.0/lookup_types.html#deep-merging-in-hiera).\n\n```\ngem install deep_merge\n```\n\nand update `merge_behavior` in your `hiera.yaml`, e.g.:\n```yaml\n---\n:backends:\n  - yaml\n:hierarchy:\n  - \"%{hostname}\"\n  - common\n# options are native, deep, deeper\n:merge_behavior: deeper\n```\n\nWith [Puppet librarian](https://github.com/rodjek/librarian-puppet) add one line to `Puppetfile`:\n\nstable release:\n\n```ruby\nmod 'deric-accounts'\n```\n\ndevelopment version (master branch from github):\n```ruby\nmod 'deric-accounts', :git =\u003e 'https://github.com/deric/puppet-accounts.git'\n```\n\nand run\n\n```bash\n$ librarian-puppet install\n```\n\n## Supported versions\n\n## Tests\n\nRun tests with:\n\n```bash\n$ bundle install\n$ bundle exec rake spec\n```\n\n## Acceptance testing\n\nFastest way is to run tests on prepared Docker images:\n```\nBEAKER_set=debian9-5.5 bundle exec rake acceptance\nBEAKER_set=centos7-3.8 bundle exec rake acceptance\n```\nFor examining system state set Beaker's ENV variable `BEAKER_destroy=no`:\n\n```\nBEAKER_destroy=no BEAKER_set=debian9-6.3 bundle exec rake acceptance\n```\nand after finishing tests connect to container:\n```\ndocker exec -it adoring_shirley bash\n```\n\nWhen host machine is NOT provisioned (puppet installed, etc.):\n```\nPUPPET_install=yes BEAKER_set=debian-8 bundle exec rake acceptance\n```\n\nRun on specific OS (see `spec/acceptance/nodesets`), to see available sets:\n```\nrake beaker:sets\n```\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderic%2Fpuppet-accounts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fderic%2Fpuppet-accounts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderic%2Fpuppet-accounts/lists"}