A REST service that provides a (read-only) interface to passwd and group files. Built using connexion.

Although not practically useful, I do hope it can act as a sample connexion app with a greater focus on basic configuration and testing (using WebTest), compared to other connexion example projects. Some more details on the project structure are in project-structure.md.

If you don't care about connexion (or Flask apps), then as a Python app it might also be useful for setting up:

• Continuous Integration with travis-ci (Linux), appveyor (Windows) and azure pipelines (Mac).
• Code coverage via coveralls.
• Code quality checks with LGTM, codacy and Code Climate.
• Some basic linting configuration files that can also be used with the 'Problems' pane in Visual Studio Code.

Some details on which files are used for these tools is in automation.md.

Python 3.6 or higher.

Install the requirements:

pip install -r requirements.txt

To install as a package:

pip install .

But you can run the app (see below) without installing, so that's probably not necessary. Just run commands from the project root directory (i.e. the directory this README is in). The only difference is where you put any extra configuration files -- see the Instance folder section below.

Using Flask's built-in server:

python server.py

This will launch the app at localhost:5000.

To override the host and port, use the --host and --port arguments respectively, e.g.:

# listen on all assigned IPs on port 8080
python server.py --host=0.0.0.0 --port=8080

Assuming the default host and port, once running, you can make a GET request to

http://localhost:5000/api/users

to see the content of your passwd file returned as JSON. For more information, the swagger-ui-generated documentation for the API can be found at:

http://localhost:5000/api/ui/

By default the passwd file is assumed to be at /etc/passwd, and the group file at /etc/group. To use different locations, you have a couple of options:

This is a standard Flask practice, so should be preferred. Place a config.cfg file in the instance folder of the app, which, if you are running the server without having installed passaas as a package, is probably a directory called instance in the directory of the README you are reading now, i.e.:

/README.md
/instance
    /config.cfg

The instance directory does not exist by default, so you will need to create it, as well as the config.cfg file.

If you did install passaas as a package, then it should be placed in the folder $PREFIX/var/passaas.app-instance. You can find out $PREFIX from sys.prefix. For example, if you have used venv to create a virtual environment called venv (as is widely recommended), then sys.prefix will point to the folder venv where you created the virtual environment and the instance folder is venv/var/passaas.app-instance.

Note that the exact name of the instance folder in the installed-package case differs a bit from that given in the flask documentation, presumably because of how we get to the flask app underlying the connexion app itself.

The content of the config.cfg should specify PASSWD_PATH and GROUP_PATH as absolute paths, e.g.:

PASSWD_PATH = "/abs/path/to/passwd"
GROUP_PATH = "/abs/path/to/group"

Alternatively, you can use the --passwd and --group options when lauching the server:

python server.py --passwd=/path/to/some/other/passwd --group=/path/to/some/other/group

If for some reason you like to really complicate life for yourself and you use an instance folder and provide command-line options, be aware that the instance folder configuration overrides any command-line option provided.

To run the unit tests:

pip install -r test-requirements.txt
python setup.py test

See the wsgi.py file for something that can be used as a WSGI module with uwsgi. To deploy on port 8080 with 2 workers:

uwsgi --http :8080 --wsgi wsgi --processes 2

There are also command line options to override the default passwd and group locations: add the arguments --set passwd=/path/to/passwd and --set group=/path/to/group to the above invocation. The instance folder approach works unchanged.

• Examples of using connexion with testing are incredibly thin on the ground. connexion-tiny-petstore was invaluable in getting going. It deserves your love and github stars (if that's your sort of thing).

• Other sample connexion apps are connexion-example, python-flask-microservice, and flask-connexion-rest. These are much simpler to understand, but if you are new to both Flask and connexion, it's hard to see how you would change these apps so they can be tested.

• Testing was done with WebTest.

• pytest-azurepipelines made publishing test results on Azure pipelines very easy.

• I turned on codacy checking, but ended up turning off the prospector and pylint checks because the configuration files in the project didn't seem to be picked up. Also the remark-lint got turned off because its default checks conflict with markdownlint which I use with Visual Studio Code. codacy's rating of the code quality may therefore be less judgemental than it ought to be.

The MIT License.