Ansible ZNC

This project helps you install and set up the ZNC IRC bouncer.

It comes with the ClientBuffer module, which allows managing multiple chat sessions for each account.

Since this project uses a Docker container, using the znc command directly isn't simple. To run a password command, you can use this command if you have Docker installed:

docker run -it --rm triplepoint/docker-znc:latest znc --makepass

Requirements

You need a running Docker environment on your host machine to use this project. The geerlingguy.docker role can help with that.

Role Variables

For details on configuring ZNC, check the ZNC configuration documentation.

For information on ZNC's global, user, and network modules, see the ZNC module documentation.

ZNC Installation Settings

znc_exec_user: znc-admin    # The user account under which ZNC will run
znc_exec_user_and_group_id: 1066  # User ID and group ID for the exec user
znc_docker_image_version: 0.1.6   # The version of the Docker image to use
znc_install_version: 1.6.5  # The version of ZNC installed in the Docker image
znc_config_root: /etc/znc   # Where to find ZNC's configuration files

Global ZNC Configuration

znc_max_buffer_size: 100000    # Max size for any user buffer (default value)
znc_port: 6666                 # Port for ZNC to listen on
znc_ipv4: true                 # Enable IPv4 support
znc_ipv6: false                # Enable IPv6 support?
znc_ssl: true                  # Should ZNC use SSL connections?
znc_ssl_certfile: "{{ znc_config_root }}/znc.pem"   # Location of the SSL certificate (generated during setup)
znc_global_modules:             # Global modules to be installed for all users and networks
  - webadmin

User Configuration for ZNC

znc_users:                                # Recommended to have an admin user without networks for ZNC administration
  - name: admin
    password:                             # Generated with `znc --makepass`. Example for password "admin".
      method: "sha256"
      hash: "481fe84cc70161b20eb0c487d212e8b94cabb45cb9f08b6c51cc2c0131c1b42e"
      salt: "J*;s-Z!gjJ:oJ.kThRZv"
    nick: adminuser
    realname: Admin ZNC User
    admin: true                           # At least one admin user is needed
    allow: "*"                            # Optional settings
    altnick: adminuser_                   # Optional alternative nickname
    autoclearchanbuffer: true             # Optional, false if using clientbuffer
    autoclearquerybuffer: true            # Optional, false if using clientbuffer
    buffer: 100000                        # Optional buffer size
    chanmodes: "+stn"                     # Optional channel modes
    ident: adminuser_                     # Optional identifier
    multiclients: false                   # Optional, allow multiple clients?
    networks:                             # Optional, needed to connect to networks
      freenode:
        server: chat.freenode.net
        port: 6697
        ssl: true
        password: ""                      # Optional password for the remote chat server
        channels:                         # Optional list of channels to connect to
          - "#freenode"                   # Use comments for YAML if there's a hash in the channel name
        modules:                          # Optional list of network-specific modules
          - route_replies
          - keepnick
          - clientbuffer                  # Disable `autoclearchanbuffer` and `autoclearquerybuffer` if enabled for this user
    modules:                              # User-specific modules
      - chansaver
      - controlpanel
      - webadmin

Dependencies

None required.

Example Playbook

- hosts: whatever
  roles:
    - triplepoint.znc

Role Testing

This role is tested using molecule, with pipenv managing dependencies and the Python environment.

Setting Up Your Environment

pip install pipenv

Note: Avoid using pip-tools as it may cause compatibility issues.

After pipenv is installed, create the virtual environment with:

pipenv install --ignore-pipfile

Running Tests

Run the tests once your environment is ready with:

pipenv run molecule test

Updating the Lock File

If you change package requirements or find outdated dependencies, regenerate the Pipfile.lock:

pipenv lock

Remember to check in the new Pipfile.lock.

License

MIT