[](https://git.digdeo.fr/digdeo-system/dd-ansible-syspass/commits/master) [](https://git.digdeo.fr/digdeo-system/dd-ansible-syspass/commits/master)
# digdeo-ansible-syspass
**Module page**: https://pypi.org/project/digdeo-syspass-ansible-lookup/
**Documentation**: https://www.readthedoc.io/digdeo-syspass-ansible-lookup
**Bug Tracker**: https://gitdev.digdeo.fr/digdeo-projets-floss1/digdeo-syspass-ansible-lookup/issues
## Introduction
**digdeo-ansible-syspass** is a [ansible](https://ansible.com) [lookup](https://docs.ansible.com/ansible/latest/plugins/lookup.html) plugin write in [python](https://www.python.org).
That program is a [ansible](https://ansible.com) plugin interface it use [digdeo-syspass-client](https://pypi.org/project/digdeo-syspass-client/) to dialog with the [syspass](https://www.syspass.org) API.
It plugin is dedicated to lookup password's from a [syspass](https://www.syspass.org) server.
## Installation
### Normal installation
```shell script
python3 -m venv venv
. venv/bin/activate
pip install digdeo-syspass-ansible-lookup
```
### Force a Ansible version
```shell script
python3 -m venv venv
. venv/bin/activate
pip install wheel "ansible == 2.7.17"
pip install digdeo-syspass-ansible-lookup
```
### Force libxml
On Linux (and most other well-behaved operating systems), pip will manage to build the source distribution as long as ``libxml2`` and ``libxslt`` are properly installed, including development packages, i.e. header files, etc.
See the requirements section above and use your system package management tool to look for packages like ``libxml2-dev`` or ``libxslt-devel``. If the build fails, make sure they are installed.
Alternatively, setting ``STATIC_DEPS=true`` will download and build both libraries automatically in their latest version, e.g.
```shell script
STATIC_DEPS=true pip install lxml.
```
Note that module use [digdeo-syspass-client](https://pypi.org/project/digdeo-syspass-client/) python module
Please pay attention about config.yml file in case you need more information's.
**DISCLAIMER:**<br>
This module has been heavily inspired by https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/lookup/password.py for password generation and term handling and thus is under GPL.
lookup: syspass
author: Gousseaud Gaëtan <gousseaud.gaetan.pro@gmail.com>, Pierre-Henry Muller <pierre-henry.muller@digdeo.fr>, Jérôme Ornech <jornech@digdeo.fr>
short_description: get syspass user password and syspass API client
description:
- This lookup returns the contents from Syspass database, a user's password more specificly. Other functions are also implemented for further use.
ansible_version: ansible 2.7.17 and more with mitogen
python_version: 3.5 and more
syspass_version: 3.0, 3.1
### Ansible usage:
#### Example 1
**Vars set inside common ansible sub-structure directory**
In case you use the group name `all`.
* Create a sub directory structure `./group_vars/all` and enter inside it directory
* copy paste you variable with right value inside a file name **syspass.yml**
```
syspass_auth_token: ##################################################
syspass_token_pass: ##################################################
syspass_verify_ssl: True
syspass_api_url: ##################################################
syspass_api_version: 3.1
syspass_debug: False
syspass_debug_level: 3
syspass_verbose: True
syspass_verbose_level: 3
```
* start you playbook with ``ansible-playbook playbook.yml``
#### Example 2
**Vars set inside the playbook file**
In case you use the group name `all` the playbook can look like that:
```
--- # -*- mode: yaml; coding: utf-8 -*-
- hosts: all
vars:
syspass_default_length: 42
syspass_auth_token: ##################################################
syspass_token_pass: ##################################################
syspass_verify_ssl: True
syspass_api_url: ##################################################
syspass_api_version: 3.1
syspass_debug: False
syspass_debug_level: 3
syspass_verbose: True
syspass_verbose_level: 3
tasks:
- name: SysPass | Force virtual Environement
set_fact:
ansible_python_interpreter: "/usr/bin/env python"
- name: SysPass | Minimal test | get and if not exist insert
debug:
msg: "{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}"
register: pass1
changed_when: false
- name: SysPass | Minimal test | get and compare
debug:
msg: "{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}"
register: pass2
changed_when: pass1.msg == pass2.msg
failed_when: pass1.msg != pass2.msg
```
### Ansible Vault usage:
In case you use the group name `all`.
* Create a sub directory structure `./group_vars/all` and enter inside it directory
* use command line interface for create **syspass.yml** file `ansible-vault create syspass.yml`
* edit the **syspass.yml** file `ansible-vault edit syspass.yml`
* copy paste you variable with right value inside **syspass.yml** file
```
syspass_auth_token: ##################################################
syspass_token_pass: ##################################################
syspass_verify_ssl: True
syspass_api_url: ##################################################
syspass_api_version: 3.1
syspass_debug: False
syspass_debug_level: 3
syspass_verbose: True
syspass_verbose_level: 3
```
* create a file to store the vault password ``echo "password1234" > /my_directory/vault_passwd"``
* export env var ``DEFAULT_VAULT_PASSWORD_FILE`` via ``export DEFAULT_VAULT_PASSWORD_FILE="/my_directory/vault_passwd"``
* start you playbook with ``ansible-playbook --vault-password-file=$DEFAULT_VAULT_PASSWORD_FILE playbook.yml``
#### Summary
```
> cd directory_where_is_my_ansible.cfg_file
> mkdir -p group_vars/all
> cd group_vars/all
> ansible-vault create syspass.yml
New Vault password:
Confirm New Vault password:
> ansible-vault edit syspass.yml
Vault password:
syspass_auth_token: ##################################################
syspass_token_pass: ##################################################
syspass_verify_ssl: True
syspass_api_url: ##################################################
syspass_api_version: 3.1
syspass_debug: False
syspass_debug_level: 3
syspass_verbose: True
syspass_verbose_level: 3
~
~
~
~
-- INSERTION --
^Z :wq
> export DEFAULT_VAULT_PASSWORD_FILE="/my_private_directory/vault_passwd"
> echo "password1234" > $DEFAULT_VAULT_PASSWORD_FILE
> cd directory_where_is_my_ansible.cfg_file
> ansible-playbook --vault-password-file=$DEFAULT_VAULT_PASSWORD_FILE playbooks/playbook.yml
```
Parameters:
-----------
- **chars**: (Optional)
Type of chars used during a password generation,
Allowed value: ``ascii_letters``, ``digits``, ``allowed_punctuation``
Default value: ['ascii_letters','digits','allowed_punctuation']
- **psswd_length**: (Optional)
password length, during a password generation, that value is automatically clamped from ``password_length_min`` and ``password_length_max``
Default value: 42
- **password**: (Optional)
Directly impose a password, it shortcut the password generation
- **hostname**: (Optional is set by Ansible)
Require by Ansible, it correspond to Ansible host, you can impose a specific host from here
- **account**:
Match with Syspass API Account https://syspass-doc.readthedocs.io/en/3.1/application/api.html#accounts
- **login**:
login given to created account
- **category**:
Match with Syspass API Categories https://syspass-doc.readthedocs.io/en/3.1/application/api.html#categories
- **customer**:
Match with Syspass API Clients https://syspass-doc.readthedocs.io/en/3.1/application/api.html#clients
- **customer_desc**: (Optional)
Match with Syspass API Clients creation/description https://syspass-doc.readthedocs.io/en/3.1/application/api.html#clients
- **tags**:
Match with Syspass API Tags https://syspass-doc.readthedocs.io/en/3.1/application/api.html#tags
- **url**:
url given to created account (Optional)
- **notes**:
notes given to created account (Optional)
- **state**:
Default Value: ``present``
Allowed Value: ``present`` or ``absent``
- **private**: self.private,
is this password private for users who have access or public for all users in acl (default false)
- **privategroup**: self.privategroup,
is private only for users in same group (default false)
- **expireDate**: self.expireDate
expiration date given to created account (Optional)
Allowed Value: Expire date in UNIX timestamp format
notes:
-----
- Account is only created if exact name has no match.
- A different field passed to an already existing account wont modify it.
- Utility of tokenPass: https://github.com/nuxsmin/sysPass/issues/994#issuecomment-409050974
- Rudimentary list of API accesses (Deprecated): https://github.com/nuxsmin/sysPass/blob/d0056d74a8a2845fb3841b02f4af5eac3e4975ed/lib/SP/Services/Api/ApiService.php#L175
- Usage of ansible vars: https://github.com/ansible/ansible/issues/33738#issuecomment-350819222
syspass function list:
SyspassClient:
Account:
-AccountSearch
-AccountViewpass
-AccountCreate
-AccountDelete
-AccountView
Category:
-CategorySearch
-CategoryCreate
-CategoryDelete
Client:
-ClientSearch
-ClientCreate
-ClientDelete
Tag:
-TagCreate
-TagSearch
-TagDelete
UserGroup:
- UserGroupCreate
- UserGroupSearch
- UserGroupDelete
Others:
-Backup
### IN PLAYBOOK ###
NOTE: Default values are handled
##### USAGE 1 #####
```yamlex
- name: SysPass | Minimal test | get and if not exist insert
debug:
msg: "{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}"
register: pass1
changed_when: false
- name: SysPass | Minimal test | get and compare
debug:
msg: "{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}"
register: pass2
changed_when: pass1.msg == pass2.msg
failed_when: pass1.msg != pass2.msg
```
**Authors**:
Gousseaud Gaëtan <gousseaud.gaetan.pro@gmail.com>
Pierre-Henry Muller <pierre-henry.muller@digdeo.fr>
Jérôme Ornech <i.dont.share.my.mail@nothing.fr>
Raw data
{
"_id": null,
"home_page": "https://git.digdeo.fr/digdeo-system/digdeo-syspass-ansible-lookup",
"name": "digdeo-syspass-ansible-lookup",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "DigDeo Syspass Ansible Lookup",
"author": "DigDeo",
"author_email": "pierre-henry.muller@digdeo.fr",
"download_url": "https://files.pythonhosted.org/packages/95/4e/0ff9d37df35d9d24acc6e7089d6fd65c7464beb5558a8a41d4fc2c4801f6/digdeo_syspass_ansible_lookup-0.3.3.tar.gz",
"platform": null,
"description": "[](https://git.digdeo.fr/digdeo-system/dd-ansible-syspass/commits/master) [](https://git.digdeo.fr/digdeo-system/dd-ansible-syspass/commits/master)\n\n# digdeo-ansible-syspass\n\n**Module page**: https://pypi.org/project/digdeo-syspass-ansible-lookup/ \n**Documentation**: https://www.readthedoc.io/digdeo-syspass-ansible-lookup \n**Bug Tracker**: https://gitdev.digdeo.fr/digdeo-projets-floss1/digdeo-syspass-ansible-lookup/issues \n\n## Introduction\n**digdeo-ansible-syspass** is a [ansible](https://ansible.com) [lookup](https://docs.ansible.com/ansible/latest/plugins/lookup.html) plugin write in [python](https://www.python.org).\n\nThat program is a [ansible](https://ansible.com) plugin interface it use [digdeo-syspass-client](https://pypi.org/project/digdeo-syspass-client/) to dialog with the [syspass](https://www.syspass.org) API. \n\nIt plugin is dedicated to lookup password's from a [syspass](https://www.syspass.org) server.\n\n## Installation\n\n### Normal installation\n```shell script\npython3 -m venv venv\n. venv/bin/activate\npip install digdeo-syspass-ansible-lookup\n```\n\n### Force a Ansible version\n```shell script\npython3 -m venv venv\n. venv/bin/activate\npip install wheel \"ansible == 2.7.17\"\npip install digdeo-syspass-ansible-lookup\n```\n\n### Force libxml\n\nOn Linux (and most other well-behaved operating systems), pip will manage to build the source distribution as long as ``libxml2`` and ``libxslt`` are properly installed, including development packages, i.e. header files, etc. \n\nSee the requirements section above and use your system package management tool to look for packages like ``libxml2-dev`` or ``libxslt-devel``. If the build fails, make sure they are installed.\n\nAlternatively, setting ``STATIC_DEPS=true`` will download and build both libraries automatically in their latest version, e.g. \n\n```shell script\nSTATIC_DEPS=true pip install lxml.\n```\n\n\nNote that module use [digdeo-syspass-client](https://pypi.org/project/digdeo-syspass-client/) python module \nPlease pay attention about config.yml file in case you need more information's.\n\n\n**DISCLAIMER:**<br>\nThis module has been heavily inspired by https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/lookup/password.py for password generation and term handling and thus is under GPL.\n\n lookup: syspass\n author: Gousseaud Ga\u00ebtan <gousseaud.gaetan.pro@gmail.com>, Pierre-Henry Muller <pierre-henry.muller@digdeo.fr>, J\u00e9r\u00f4me Ornech <jornech@digdeo.fr>\n short_description: get syspass user password and syspass API client\n description:\n - This lookup returns the contents from Syspass database, a user's password more specificly. Other functions are also implemented for further use.\n ansible_version: ansible 2.7.17 and more with mitogen\n python_version: 3.5 and more\n syspass_version: 3.0, 3.1\n \n### Ansible usage:\n\n#### Example 1\n**Vars set inside common ansible sub-structure directory**\n\nIn case you use the group name `all`.\n\n* Create a sub directory structure `./group_vars/all` and enter inside it directory\n* copy paste you variable with right value inside a file name **syspass.yml**\n```\nsyspass_auth_token: ##################################################\nsyspass_token_pass: ##################################################\nsyspass_verify_ssl: True\nsyspass_api_url: ##################################################\nsyspass_api_version: 3.1\nsyspass_debug: False\nsyspass_debug_level: 3\nsyspass_verbose: True\nsyspass_verbose_level: 3\n```\n* start you playbook with ``ansible-playbook playbook.yml``\n\n#### Example 2 \n**Vars set inside the playbook file**\n\nIn case you use the group name `all` the playbook can look like that:\n```\n--- # -*- mode: yaml; coding: utf-8 -*-\n\n- hosts: all\n vars:\n syspass_default_length: 42\n syspass_auth_token: ##################################################\n syspass_token_pass: ##################################################\n syspass_verify_ssl: True\n syspass_api_url: ##################################################\n syspass_api_version: 3.1\n syspass_debug: False\n syspass_debug_level: 3\n syspass_verbose: True\n syspass_verbose_level: 3\n tasks:\n - name: SysPass | Force virtual Environement\n set_fact:\n ansible_python_interpreter: \"/usr/bin/env python\"\n - name: SysPass | Minimal test | get and if not exist insert\n debug:\n msg: \"{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}\"\n register: pass1\n changed_when: false\n - name: SysPass | Minimal test | get and compare\n debug:\n msg: \"{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}\"\n register: pass2\n changed_when: pass1.msg == pass2.msg\n failed_when: pass1.msg != pass2.msg\n```\n\n### Ansible Vault usage:\n\nIn case you use the group name `all`.\n\n* Create a sub directory structure `./group_vars/all` and enter inside it directory\n* use command line interface for create **syspass.yml** file `ansible-vault create syspass.yml`\n* edit the **syspass.yml** file `ansible-vault edit syspass.yml`\n* copy paste you variable with right value inside **syspass.yml** file\n```\nsyspass_auth_token: ##################################################\nsyspass_token_pass: ##################################################\nsyspass_verify_ssl: True\nsyspass_api_url: ##################################################\nsyspass_api_version: 3.1\nsyspass_debug: False\nsyspass_debug_level: 3\nsyspass_verbose: True\nsyspass_verbose_level: 3\n```\n* create a file to store the vault password ``echo \"password1234\" > /my_directory/vault_passwd\"``\n* export env var ``DEFAULT_VAULT_PASSWORD_FILE`` via ``export DEFAULT_VAULT_PASSWORD_FILE=\"/my_directory/vault_passwd\"``\n* start you playbook with ``ansible-playbook --vault-password-file=$DEFAULT_VAULT_PASSWORD_FILE playbook.yml``\n\n#### Summary\n```\n> cd directory_where_is_my_ansible.cfg_file\n> mkdir -p group_vars/all\n> cd group_vars/all\n> ansible-vault create syspass.yml\nNew Vault password: \nConfirm New Vault password: \n> ansible-vault edit syspass.yml\nVault password:\nsyspass_auth_token: ##################################################\nsyspass_token_pass: ##################################################\nsyspass_verify_ssl: True\nsyspass_api_url: ##################################################\nsyspass_api_version: 3.1\nsyspass_debug: False\nsyspass_debug_level: 3\nsyspass_verbose: True\nsyspass_verbose_level: 3\n~ \n~ \n~ \n~ \n-- INSERTION -- \n^Z :wq\n> export DEFAULT_VAULT_PASSWORD_FILE=\"/my_private_directory/vault_passwd\"\n> echo \"password1234\" > $DEFAULT_VAULT_PASSWORD_FILE\n> cd directory_where_is_my_ansible.cfg_file\n> ansible-playbook --vault-password-file=$DEFAULT_VAULT_PASSWORD_FILE playbooks/playbook.yml\n```\n\nParameters:\n-----------\n\n- **chars**: (Optional)\n \n Type of chars used during a password generation, \n \n Allowed value: ``ascii_letters``, ``digits``, ``allowed_punctuation``\n \n Default value: ['ascii_letters','digits','allowed_punctuation']\n \n- **psswd_length**: (Optional)\n\n password length, during a password generation, that value is automatically clamped from ``password_length_min`` and ``password_length_max``\n\n Default value: 42\n \n- **password**: (Optional)\n\n Directly impose a password, it shortcut the password generation\n \n- **hostname**: (Optional is set by Ansible)\n\n Require by Ansible, it correspond to Ansible host, you can impose a specific host from here\n\n- **account**: \n \n Match with Syspass API Account https://syspass-doc.readthedocs.io/en/3.1/application/api.html#accounts\n \n- **login**:\n \n login given to created account\n \n- **category**:\n\n Match with Syspass API Categories https://syspass-doc.readthedocs.io/en/3.1/application/api.html#categories\n \n- **customer**:\n\n Match with Syspass API Clients https://syspass-doc.readthedocs.io/en/3.1/application/api.html#clients\n \n- **customer_desc**: (Optional)\n\n Match with Syspass API Clients creation/description https://syspass-doc.readthedocs.io/en/3.1/application/api.html#clients\n\n- **tags**:\n\n Match with Syspass API Tags https://syspass-doc.readthedocs.io/en/3.1/application/api.html#tags\n \n- **url**: \n\n url given to created account (Optional)\n \n- **notes**:\n\n notes given to created account (Optional)\n \n- **state**:\n\n Default Value: ``present``\n Allowed Value: ``present`` or ``absent``\n \n- **private**: self.private,\n\n is this password private for users who have access or public for all users in acl (default false)\n \n- **privategroup**: self.privategroup,\n\n is private only for users in same group (default false)\n \n- **expireDate**: self.expireDate\n\n expiration date given to created account (Optional)\n \n Allowed Value: Expire date in UNIX timestamp format\n\n \nnotes:\n-----\n- Account is only created if exact name has no match.\n- A different field passed to an already existing account wont modify it.\n- Utility of tokenPass: https://github.com/nuxsmin/sysPass/issues/994#issuecomment-409050974\n- Rudimentary list of API accesses (Deprecated): https://github.com/nuxsmin/sysPass/blob/d0056d74a8a2845fb3841b02f4af5eac3e4975ed/lib/SP/Services/Api/ApiService.php#L175\n- Usage of ansible vars: https://github.com/ansible/ansible/issues/33738#issuecomment-350819222\n \n syspass function list:\n SyspassClient:\n Account:\n -AccountSearch\n -AccountViewpass\n -AccountCreate\n -AccountDelete\n -AccountView\n Category:\n -CategorySearch\n -CategoryCreate\n -CategoryDelete\n Client:\n -ClientSearch\n -ClientCreate\n -ClientDelete\n Tag:\n -TagCreate\n -TagSearch\n -TagDelete\n UserGroup:\n - UserGroupCreate\n - UserGroupSearch\n - UserGroupDelete\n Others:\n -Backup\n\n### IN PLAYBOOK ###\n\nNOTE: Default values are handled \n\n##### USAGE 1 #####\n```yamlex\n - name: SysPass | Minimal test | get and if not exist insert\n debug:\n msg: \"{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}\"\n register: pass1\n changed_when: false\n\n - name: SysPass | Minimal test | get and compare\n debug:\n msg: \"{{ lookup('syspass', 'Account Name minimal', login='mylogin', category='MySQL', customer='PREP') }}\"\n register: pass2\n changed_when: pass1.msg == pass2.msg\n failed_when: pass1.msg != pass2.msg\n```\n**Authors**:\nGousseaud Ga\u00ebtan <gousseaud.gaetan.pro@gmail.com>\nPierre-Henry Muller <pierre-henry.muller@digdeo.fr>\nJ\u00e9r\u00f4me Ornech <i.dont.share.my.mail@nothing.fr>\n",
"bugtrack_url": null,
"license": "GNU GENERAL PUBLIC LICENSE Version 3",
"summary": "DigDeo Syspass Ansible Lookup",
"version": "0.3.3",
"project_urls": {
"Homepage": "https://git.digdeo.fr/digdeo-system/digdeo-syspass-ansible-lookup"
},
"split_keywords": [
"digdeo",
"syspass",
"ansible",
"lookup"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be073b34a3dc280eb12f73d0ebc30a288b92942effdfe4a307f8181724e91af1",
"md5": "6005356f7830a282c500af94982d24e7",
"sha256": "0d5fee6b6a91a81ed977b86c079c99a69d6844311d917ec9ccbc811096cae682"
},
"downloads": -1,
"filename": "digdeo_syspass_ansible_lookup-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6005356f7830a282c500af94982d24e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 29268,
"upload_time": "2024-09-21T20:25:48",
"upload_time_iso_8601": "2024-09-21T20:25:48.771841Z",
"url": "https://files.pythonhosted.org/packages/be/07/3b34a3dc280eb12f73d0ebc30a288b92942effdfe4a307f8181724e91af1/digdeo_syspass_ansible_lookup-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "954e0ff9d37df35d9d24acc6e7089d6fd65c7464beb5558a8a41d4fc2c4801f6",
"md5": "a8fb9ab17d44abc93c83b100f9f57d14",
"sha256": "ac2becc43e78bd4c7434b171269e5495b26b2a3f83cbe5e11fab1734accc3bb4"
},
"downloads": -1,
"filename": "digdeo_syspass_ansible_lookup-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "a8fb9ab17d44abc93c83b100f9f57d14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 39032,
"upload_time": "2024-09-21T20:25:50",
"upload_time_iso_8601": "2024-09-21T20:25:50.617249Z",
"url": "https://files.pythonhosted.org/packages/95/4e/0ff9d37df35d9d24acc6e7089d6fd65c7464beb5558a8a41d4fc2c4801f6/digdeo_syspass_ansible_lookup-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-21 20:25:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "digdeo-syspass-ansible-lookup"
}
JSON