# salt.beacons.btmp

Beacon to fire events at failed login of users

Added in version 2015.5.0.

## Example Configuration

    # Fire events on all failed logins
    beacons:
      btmp: []

    # Matching on user name, using a default time range
    beacons:
      btmp:
        - users:
            gareth:
        - defaults:
            time_range:
                start: '8am'
                end: '4pm'

    # Matching on user name, overriding the default time range
    beacons:
      btmp:
        - users:
            gareth:
                time_range:
                    start: '8am'
                    end: '4pm'
        - defaults:
            time_range:
                start: '8am'
                end: '4pm'

    # Matching on group name, overriding the default time range
    beacons:
      btmp:
        - groups:
            users:
                time_range:
                    start: '8am'
                    end: '4pm'
        - defaults:
            time_range:
                start: '8am'
                end: '4pm'

## Use Case: Posting Failed Login Events to Slack

This can be done using the following reactor SLS:

    report-wtmp:
      runner.salt.cmd:
        - args:
          - fun: slack.post_message
          - channel: mychannel      # Slack channel
          - from_name: someuser     # Slack user
          - message: "Failed login from `{{ data.get('user', '') or 'unknown user' }}` on `{{ data['id'] }}`"

Match the event like so in the master config file:

    reactor:

      - 'salt/beacon/*/btmp/':
        - salt://reactor/btmp.sls

Note

This approach uses the `slack execution module` directly on the master, and therefore requires that the master has a slack API key in its configuration:

    slack:
      api_key: xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX

See the `slack execution module` documentation for more information. While you can use an individual user's API key to post to Slack, a bot user is likely better suited for this. The `slack engine` documentation has information on how to set up a bot user.

salt.beacons.btmp.beacon(config)

  Read the last btmp file and return information on the failed logins

salt.beacons.btmp.validate(config)

  Validate the beacon configuration