DEBOPS.FCGIWRAP(5)

NAME
debops.fcgiwrap - Manage multiple fcgiwrap instances with Ansible

SYNOPSIS

debops run service/fcgiwrap [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

fcgiwrap <https://github.com/gnosek/fcgiwrap> is a lightweight FastCGI server which can be set up behind nginx server to run CGI applications. This role allows you to setup separate instances of fcgiwrap on different user accounts, each one accessible through its own UNIX socket.

GETTING STARTED

  Initial configuration

debops.fcgiwrap role will by default disable the system-wide fcgiwrap instance. In its place you will be able to create per-user fcgiwrap instances, each with their own socket, running as an unprivileged user.

Each instance will make sure that specified user account and group exists, you can specify additional configuration to create accounts with a specific shell or home directory. By default system accounts (UID/GID < 1000) are used.

This role requires debops.core role to configure local fact which provides the name of the init system used by the host (it does not need to be included in the role dependencies, it's enough that it is run once at the beginning of the playbook).

  Example inventory

To enable fcgiwrap on a host by hand, you need to add that host to [debops_service_fcgiwrap] host group in Ansible inventory. You will also need to specify an instance to create. Example inventory:

# inventory/hosts
[debops_service_fcgiwrap]
hostname
# inventory/host_vars/hostname/fcgiwrap.yml
fcgiwrap__instances:
  - name: 'webapp'
    user: 'webapp'
    group: 'webapp'
    home: '/srv/www/webapp'
    shell: '/bin/false'

This configuration will ensure that specified user account exists and will start fcgiwrap on that account using system service script. The socket used by this instance will be created as /run/fcgiwrap-webapp.socket.

  Example playbook

debops.fcgiwrap is designed to be used from a playbook or a role as role dependency. Here's an example configuration:

---
- name: Set up web application
  hosts: [ 'debops_service_fcgiwrap' ]
  become: True
  roles:
    - role: debops.fcgiwrap
      tags: [ 'role::fcgiwrap' ]
      fcgiwrap__instances:
        - name: 'webapp'
          user: 'webapp'
          group: 'webapp'

DEFAULT VARIABLES: CONFIGURATION

some of debops.fcgiwrap default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  fcgiwrap__instances

List of fcgiwrap user instances, each one defined by a YAML dictionary. These instances will configure system services (init scripts on sysvinit and units on systemd) which will start fcgiwrap unprivileged on specified user account.

List of known parameters:

name
    Required. Name of the instance, will be used as the name of the init scripts/unit files and socket.

user
    Required. Name of the user account to use for this instance.

group
    Primary group of a given user account to use for this instance.

home
    Path to the home directory for the user account. If account does not exist, it will be created automatically with specified home directory.

createhome
    Boolean, by default False. Specify if the user home directory should be created if it does not exist.

shell
    Shell used by specified user account.

system
    Boolean, by default True. If the account does not exist, it will be created as a "system" account with its UID/GID < 1000.

socket_user
    Owner of the socket used by this fcgiwrap instance.

socket_group
    Group which has access to this instance's socket.

socket_mode
    File permissions set on this instance's socket.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others