README.rst

==============
Mailman3 tools
==============

This is a collection of MM3 tools to aid in daily administration of
Mailman3 (MM3) installations. Main goal was not to replicate existing
functionality but mainly augument existing toolkit with missing
functions.

.. ..contents:: Table of contents
  :depth: 2

overall this toolkit is aimed at Docker-based mailman installations
using maxking's docker-compose project.

Easiest way to use those tools is to mount them inside mailman-web container
which already contains mailmanclient library and is running::

  ...
  mailman-web:
    image: maxking/mailman-web:0.1.7
    container_name: mailman-web
    ...
    volumes:
      ...
      - $MAILMAN_WEB_DIR:/opt/mailman-web-data
      - /opt/Mailman-tools:/opt/mailman-tools
      ...

this way tools are accessible from host environment via "docker exec" or
"docker-compose exec" invocations::

  $ docker exec -it mailman-web python /opt/mailman-tools/list_stats.py --all > stats.json

Tools
=====

list_stats.py
-------------

obtain list statistics::

  "mylist": {
    "owners": 2,
    "messages_held": 0,
    "members": 7,
    "list_fqdn_name": "mylist@lists.stanford.edu",
    "last_digest": "2018-02-09T19:09:55.256954",
    "nonmembers": 26,
    "subscription_requests": 0,
    "last_post": "2017-10-20T16:34:20.959539",
    "moderators": 3
  }

One can use jq to format output into something more concise::

  $ docker exec -it mailman-web python /opt/mailman-tools/list_stats.py --all > stats.json
  $ jq -cr 'to_entries[]| { (.key): {"held": (.value | .messages_held), "requests": (.value | .subscription_requests)} }' stats.json

manage_list.py
==============

this is the command-line interface for interaction with mailing list
operational functions: moderate requests/messages.

this tool utilizes following subcommand structure:

* held

  * list
  * approve
  * reject
  * discard
  * delete
  * defer

* requests

  * list
  * approve
  * discard
  * defer

for example moderate messages::

  $ LIST_NAME=mylist@lists.stanford.edu
  $ docker exec -it mailman-web python /opt/mailman-tools/manage_list.py $LIST_NAME held list > held.json
  $ jq -r .[].request_id held.json  # print all request_id's
  $ docker exec -it mailman-web python /opt/mailman-tools/manage_list.py $LIST_NAME held discard --id=1234

subscription request moderation is handled in a similar fashion::

  $ LIST_NAME=mylist@lists.stanford.edu
  $ docker exec -it mailman-web python /opt/mailman-tools/manage_list.py $LIST_NAME requests list > requests.json
  $ jq -r .[].token requests.json  # print all tokens currently active
  $ docker exec -it mailman-web python /opt/mailman-tools/manage_list.py $LIST_NAME requests discard --token=abcd123xyz

manage_settings.py
==================

this script helps to dump/restore/update list settings::

  $ LIST_NAME=mylist@lists.stanford.edu
  $ docker exec -i mailman-web python /opt/mailman-tools/manage_settings.py --dump $LIST_NAME > /${LIST_NAME}.json
  $ vi ${LIST_NAME}.json
  ...edit out all the fields that you do not intend to modify
  ...and leave only ones that you want modify
  $ cat %{LIST_NAME}.json | docker exec -t mailman-web python /opt/mailman-tools/manage_settings.py --update $LIST_NAME
  $ # Or simply update settings right from CLI:
  $ docker exec -t mailman-web python /opt/mailman-tools/manage_settings.py --set autoresponse_request_text="your request awaits approval" $LIST_NAME

manage_users.py (WIP)
=====================

dump/restore User subscriptions for specific mailing list. It's not complete yet

member_settings.py
==================

dump member subscription preferences for specified mailing list::

  $ LIST_NAME=mylist@lists.stanford.edu
  $ docker exec -t mailman-web python /opt/mailman-tools/member_settings.py --member=me@stanford.edu --member=him@stanford.edu $LIST_NAME

remove_user.py
==============

unsubscribes users from ML::

  $ LIST_NAME=mylist@lists.stanford.edu
  $ docker exec -t mailman-web python /opt/mailman-tools/remove_user.py --member=me@stanford.edu --member=him@stanford.edu $LIST_NAME

stats2omd.py
============

Helper script for processing bulk list stats (produced by list_stats.py) into
OMD (Check_mk) digestable format::

  $ docker-compose -f mailman-docker-compose.yml exec -T mailman-web python /opt/mailman-tools/list_stats.py > stats.json
  $ python stats2omd.py < stats.json

note that one doesn't have to run it within container as it doesn't use
any of the mailman APIs it's just a post-processing tool

sync_users.py
=============

synchronize list subscribers with a given list::

  $ LIST_NAME=mylist@lists.stanford.edu
  $ cat desired_member_list | docker exec -i mailman-web python /opt/mailman-tools/sync_users.py $LIST_NAME

this will remove users that are not in specified member list file and add the ones
that are.