matrix-docker-ansible-deploy/docs/configuring-playbook-bot-buscarron.md

Setting up Buscarron (optional)

The playbook can install and configure buscarron for you.

Buscarron is bot that receives HTTP POST submissions of web forms and forwards them to a Matrix room.

Adjusting the playbook configuration

Add the following configuration to your inventory/host_vars/matrix.DOMAIN/vars.yml file:

matrix_bot_buscarron_enabled: true

# Uncomment and adjust this part if you'd like to use a username different than the default
# matrix_bot_buscarron_login: bot.buscarron

# Generate a strong password here. Consider generating it with `pwgen -s 64 1`
matrix_bot_buscarron_password: PASSWORD_FOR_THE_BOT

# Adjust accepted forms
matrix_bot_buscarron_forms:
  - name: contact # (mandatory) Your form name, will be used as endpoint, eg: buscarron.DOMAIN/contact
    room: "!yourRoomID:DOMAIN" # (mandatory) Room ID where form submission will be posted
    redirect: https://DOMAIN # (mandatory) To what page user will be redirected after the form submission
    ratelimit: 1r/m # (optional) rate limit of the form, format: <max requests>r/<interval:s,m>, eg: 1r/s or 54r/m
    hasemail: 1 # (optional) form has "email" field that should be validated
    extensions: [] # (optional) list of form extensions (not used yet)

matrix_bot_buscarron_spamlist: [] # (optional) list of emails/domains/hosts (with wildcards support) that should be rejected automatically

You will also need to add a DNS record so that buscarron can be accessed. By default buscarron will use https://buscarron.DOMAIN so you will need to create an CNAME record for buscarron. See Configuring DNS.

If you would like to use a different domain, add the following to your configuration file (changing it to use your preferred domain):

matrix_server_fqn_buscarron: "form.{{ matrix_domain }}"

Installing

After configuring the playbook, run the installation command again:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

Notes:

• the ensure-matrix-users-created playbook tag makes the playbook automatically create the bot’s user account

• if you change the bot password (matrix_bot_buscarron_password in your vars.yml file) subsequently, the bot user’s credentials on the homeserver won’t be updated automatically. If you’d like to change the bot user’s password, use a tool like synapse-admin to change it, and then update matrix_bot_buscarron_password to let the bot know its new password

Usage

To use the bot, invite the @bot.buscarron:DOMAIN to the room you specified in a config, after that any point your form to the form url, example for the contact form:

<form method="POST" action="https://buscarron.DOMAIN/contact">
<!--your fields-->
</form>

NOTE: to fight against spam, Buscarron is very aggressive when it comes to banning and will ban you if:

• if you hit the homepage (HTTP GET request to /)
• if you submit a form to the wrong URL (POST request to /non-existing-form)
• if hasemail is enabled for the form (like in the example above) and you don’t submit an email field

If you get banned, you’d need to restart the process by running the playbook with --tags=start or running systemctl restart matrix-bot-buscarron on the server.

You can also refer to the upstream documentation.