We need a tool that serves the app, notices our source code changing, automatically recompiles it, stops the previous build from being served to finally serve the new build.

CRUN - continuously Compile and Run - does exactly that. It's a go CLI application. With one command all .go files from the current directory are being watched.

Similar tools already exist but I wanted something super simple to use with some tests.

Use

// Change to directory with your app go source code
cd /path/to/my/app

// Start compiling and running app
crun

You can pass additional arguments to the binary.

// additional arguments after `--` are passed to the binary
crun -- --port=:3000

Install

Go get the package to install

go get github.com/toonketels/crun

Since Karma loads the JavaScript files for us, we won't include an index.html to bootstrap the Angular app or to initialize some Angular modules. This is nice but at the same time poses a probem. By only loading the files, we can not use Angular's dependency injection system when testing code.

We use angular-mocks to circumvent this problem.

First, install angular mocks.

bower install angular-mocks --save-dev

Modify karma.config.js to include Angular mocks.

files: [
    "node_modules/chai/chai.js",
    "src/vendor/angular/angular.js",
    "src/vendor/angular-mocks/angular-mocks.js",
    "src/js/app.js",
    "tests/**/*.js"
],

Finally, ensure the module to test is ready by including the following in each test:

beforeEach(angular.mock.module("APP"))

This will make the specific module ready to be tested. So all controllers and services defined on the module are available for testing.

You'll find an example on github.

Though we find plenty of information about Karma on their website, I found it not all obvious what the different configuration settings in its config file do. We try to explain this using an example project.

JavaScript project with Karma, mocha and chai

The project has the following directory structure (get if from github):

// Contains all source files
src/js/
src/vendor/

// Contains the tests
tests/unit/

// Contains nodejs modules
node_modules/

Install testing libs

First, install Karma and some plugins:

// Install karma, mocha adapter and chai
npm install karma karma-mocha chai --save-dev

Everything is installed in the node_modules directory. Karma is the test runner. As a test runner it:

• Starts a webserver to serve our JavaScript source and test files
• Loads all files in the correct order
• Spins up browsers to run our tests in

Mocha is a test framework. It is responsible to run our tests and report back which failed.

Chai is an assertion library. It provides a nice api to check whether our code does the things we expect it to do.

Create Karma config file

Next we create the Karma config file in our directory root:

// Create Karma config file
./node_modules/karma/bin/karma init

This will prompt us for some questions and generates a config file. Items of interests to us are:

basePath: '',

The base path tells Karma where to load our files from. Setting it to '' means all files will be looked up from the root of our project.

files: [
    "node_modules/chai/chai.js",
    "src/**/*.js",
    "tests/**/*.js"
],

Files tells Karma which files it should load relative to the base path. These are:

• All test related libraries
• Our source code to test
• The tests themselves

Note we instruct Karma to load chai.js. Forgetting this means chai will not be loaded.

What about Mocha? Doesn't it need to be loaded too?

Yes it should. However, Karma will autoload all sibling node modules starting with karma-. This means if Karma is installed in the node_modules directory, all other modules starting with karma- will be autoloaded for us. And mocha is fetched as the karma-mocha node module. No need to manually load it ourselves.

frameworks: ['mocha'],

Frameworks instructs Karma to use the mocha testing framework.

browsers: ['Chrome'],

Browsers tells Karma to run the tests in Chrome. Note, Chrome needs to be installed on our computer. Running the tests from the command line will spin up a new Chrome window.

The karma-chrome-launcher node module needs to be installed too. karma init command will auto install it for us. If you add a browser later on, don't forget to install its runner too.

port: 9876,

Karma will start its own server on this port to serve our JavaScript files and tests. The default is ok, only change it when we're already using that port.

autoWatch: true,

Auto watch instructs Karma to rerun the tests whenever a file changes.

singleRun: false

Single run tells Karma to shut down the browser when all tests have ran. This is useful for Continuous Integration systems where only one run is needed. For development, set it to false as this will keep the browser window opened. This means no time is wasted spinning up a new browser every time tests need to be executed.

Run the tests

Now we can run the tests like:

./node_modules/karma/bin/karma start

Notice we can also run the tests with ./node_modules/karma/bin/karma run. This will not spin up the server to load our test files. Use it in combination with karma start. Start will spin up the browser and load the files, run will instruct karma to rerun the tests.

Use karma-cli

It's tiresome to always do ./node_modules/karma/bin/karma start instead of just karma start. Therefore install karma-cli globally.

npm install -g karma-cli

This tool executes the Karma commands for the project in the current directory. By exposing the commands in a separate module then the Karma implementation, we can use different versions of Karma for different projects on our computer.

Note: we might have installed Karma globally before. If so, we need to delete it first as it will mess up which plugins it will autoload. For example: we might have installed karma-mocha in our project dir but not globally. Executing Karma (as global installed module) will fail to load karma-mocha (since "global" Karma will only look into the globally installed modules). Just uninstall karma as a global module and install karma-cli globally instead.

In its simplest form, just create a router instance and register HandlerFuncs to HTTP verb/path pairs. Use the router by calling Handle and ListenAndServe. A working example is shown below.

package main

import (  
    "github.com/toonketels/router"
    "net/http"
)

func main() {  
    // Create a new router
    appRouter := router.NewRouter()

    // Register a handlerFunc for GET/"hello" paths
    appRouter.Get("/hello", func(res http.ResponseWriter, req *http.Request) {
        res.Write([]byte("hello"))
    })

    // Use this router
    appRouter.Handle("/")

    // Listen for requests
    http.ListenAndServe(":3000", nil)
}

Now, let's dive a bit deeper in the package API.

HandlerFuncs

Once a router instance has been created, use its Get/Put/Post/Patch/Head/Options/Delete methods to register a handlerFunc to a route/HTTP verb pair.

// Register a handlerFunc for GET/"hello" paths
appRouter.Get("/hello", handlerFunc)

// Register a handlerFunc for PUT/"hello" paths
appRouter.Put("/hello", handlerFunc)

// Register a handlerFunc for POST/"hello" paths
appRouter.Post("/hello", handlerFunc)

// Register a handlerFunc for Patch/"hello" paths
appRouter.Patch("/hello", handlerFunc)

// Register a handlerFunc for HEAD/"hello" paths
appRouter.Head("/hello", handlerFunc)

// Register a handlerFunc for OPTIONS/"hello" paths
appRouter.Options("/hello", handlerFunc)

// Register a handlerFunc for DELETE/"hello" paths
appRouter.Delete("/hello", handlerFunc)  

You can also register multiple handlerFuncs for a given route.

// Register the handlerFuncs
appRouter.Get("/user/:userid/hello", logUser, handleUser)  

For this to work, all handlerFuncs should pass control to handlerFuncs coming after them by calling
cntxt.Next().

func loadUser(res http.ResponseWriter, req *http.Request) {

    // Grab the context for the current request
    cntxt := router.Context(req)

    // Do something

    // Pass over control to next handlerFunc
    cntxt.Next(res, req)
}

If your handlerFunc wants to protect access to certain routes, it could do so by only calling cntxt.Next() when some authorization rule validates.

func allowAccess(res http.ResponseWriter, req *http.Request) {  
    if allowUserAccess() {
        // Allows access
        router.Context(req).Next(res, req)
        return
    }
    // Denies access
}

HandlerFuncs can store data onto the requestContext to be used by handlerFuncs after them.

func loadUser(res http.ResponseWriter, req *http.Request) {  
    cntxt := router.Context(req)
    user := getUserFromDB(cntxt.Params["userid"])

    // Store the value in request specific store
    _ = cntxt.Set("user", user)

    cntxt.Next(res, req)
}

HandlerFuncs use cntxt.Get(key) to get the value. RequestContext has Set/ForceSet/Get/Delete methods all related to the data stored during the current request.

func handleUser(res http.ResponseWriter, req *http.Request) {  
    cntxt := router.Context(req)

    // Get a value from the request specific store
    if user, ok := cntxt.Get("user"); ok {
        // Do something
    }
    // Do something else
}

Remember the route /user/:userid/hello? It matches routes like /user/14/hello or /user/richard/hello. HandlerFuncs can access the values of userid on the requestContext.

func loadUser(res http.ResponseWriter, req *http.Request) {

    // Grab the userid param from the context
    userid := router.Context(req).Params["userid"]

    // Do something with it
}

As you might have noticed, handlers need to be http.HandlerFunc's. So you can use your existing ones if you don't need to access the requestContext.

Mounting handlerFuncs

Some handlerFuncs need to be executed for every request, like a logger. Instead of passing it to every registered route, we "mount" them using router.Mount().

appRouter := router.NewRouter()

// Mount handlerFuncs first
appRouter.Mount("/", logger)  
appRouter.Mount("/", allowAccess)

// Then start matching paths
appRouter.Get("/user/:userid/hello", loadUser, handleUser)  

The order in which you mounted and registered handlers, is the order in which they will be executed.

A request to /user/14/hello will result in logger to be called first, followed by allowAccess, loadUser and handleUser. That is as long as none of the handlerFunc's prevented the latter ones from executing by not calling next.

By changing the mountPath of allowAccess to /admin, we get different results.

// Mount handlerFuncs first
appRouter.Mount("/", logger)  
appRouter.Mount("/admin", allowAccess)

// Then start matching paths
appRouter.Get("/user/:userid/hello", loadUser, handleUser)  
appRouter.Get("/admin/user/:userid", loadUser, administerUserHandler)  

It the above case a request to /user/20/hello will execute logger -> loadUser -> handleUser, while a request to /admin/user/20 executes logger -> allowAccess -> loadUser -> administerUserHandler.

We see that by dividing a complex handlerFunc into multiple smaller ones, we get more code reuse. It becomes easy to create a small set of "middleware" handlers to be reused on different routes. While the last handlerFunc is generally the one responsible for generating the actual response.

Error Handling

Besides storing data and dispatching the next handlerFunc cntxt has an Error method. Let's update the loadUser handlerFunc to take errors into account.

func loadUser(res http.ResponseWriter, req *http.Request) {  
    cntxt := router.Context(req)
    user, err := getUserFromDB(cntxt.Params["userid"])
    if err != nil {

        // Let the errorHandlerFunc generate the error response.
        // We stop executing the following handlers
        cntxt.Error(res, req, err.Error(), 500)
        return
    }

    // Store the value in request specific store
    _ = cntxt.Set("user", user)

    // Pass over control to next handlerFunc
    cntxt.Next(res, req)
}

Calling cntxt.Error() notifies the requestContext an error has been made and further Next() call will be prevented. It delegates the requestHandling to a dedicated errorHandlerFunc to reply in a consistent manner.

Though calling Next() after an error will never dispatch the next HandlerFunc, it is wise to just return after the error so the current
HandlerFunc stops executing.

Previous HandlerFuncs are allowed to continue executing their code when the executing flow returns to them.

For instance, when the logger below is called, it records the time and calls the next HandlerFunc. If that handler errs, logger will resume as usual allowing it to log its output.

func logger(res http.ResponseWriter, req *http.Request) {

    // The fist handlerFunc to be executed
    // record the time when the request started
    start := time.Now()

    // Handle over control to the next handlerFunc.
    router.Context(req).Next(res, req)

    // We log once all other handlerFuncs are done executing
    // so it needs to come after our call to cntxt.Next()
    fmt.Println(req.Method, req.URL.Path, time.Since(start))
}

The actual response send to the client is handled by default ErrorRequestHandler. Which will just do http.Error(res, err, code).

Customize the response by updating your router's ErrorHandler. The function passed should comply with the ErrorHandler interface.

appRouter.ErrorHandler = func(res http.ResponseWriter, req *http.Request, err string, code int) {  
    http.Error(res, strings.ToUpper(err), code)
}

The request is passed to allow a different response to be send depending on request properties.

Similarly, configure the response generated when a route is not found by updating the router's NotFoundHandler which is a plain http.HandlerFunc.

Conclusion

With just a couple of concepts: registering requestHandlers, mounting requestHandlers and a requestContext for each request, we can do powerful things.

You can find some examples in the projects repo.

I considered the following ideas (heavily borrowing from express/connect):

• registering handlers based on HTTP verb/path combos should be easy, as this is most often used
• split complex HandlerFuncs into multiple smaller one which can be shared
• mount generic HandlerFuncs to be executed on every path
• registering and accessing paths with params (like :userid) should be easy
• store data on a requestContext, so it can be passed to later HandlerFuncs
• set a generic errorHandlerFunc and stop executing later handerFuncs as soon as an error occurs
• set a generic pageNotFound HandlerFunc
• handlers are regular http.HandlerFunc to be compatible with go

I've created the package mainly to get my feet wet in go. A couple of similar packages already exist, but writing my own made me more familiar with the language and its standard lib.

The package is fully tested and ready to be used. Code can be found on github, documentation on godoc.

Engine.io is the implementation of transport-based cross-browser/cross-device bi-directional communication layer for Socket.IO. It's WebSockets with fallbacks to make it work on the web.

Engine.io is much more low level then socket.io. It leaves things like reconnects and multiplexing up to us to implement. As such, it's similar to sock.js.

Because it starts with long-polling and does not try to do too many things, we can optimise real time connections to our needs, making it a better fit to run in production compared to socket.io.

Background

We have separated our app into an httpServer and socketServer (powered by engine.io) allowing us to spin up more instances of each depending on the load.

For this to work, we need two things:

• a Load Balancer to forward all incoming traffic to httpServer instances or socketServer instances
• a shared session store so each server instance can access the same session information

Happroxy does the loadbalancing. We use connect-redis and connect-sessions to share session information.

The problem

HttpServers and socketServers (with fallbacks) are two different beasts.

HttpServers can/should be stateless. This means that any request can be handled by any httpServer. It does not matter where the request lands.

The socketServers on the other hand requires all connections from one client to land on the same socketServer. This includes regular HTTP requests used to establish the initial connection and when using long-polling, FlashSocket and WebSocket connections.

If a WebSocket connection would downgrade to long-polling and HTTP requests would be routed to random servers, engine.io would just not work.

Haproxy

Our haproxy config needs to do two things:

• find out which traffic (HTTP and sockets) needs to be routed to socketServers and which to the httpServers
• ensure all engine.io related connections from one client always land on the same socketServer instance

Haproxy config file

Example haproxy config file:

defaults  
    mode    http
    retries 3
    # option redispatch
    timeout connect  5000
    timeout client  10000
    timeout server  10000


# Application can reached on port 3000
# Load balancer will split traffic to http
# and socket servers based on /engine.io prefix.
frontend all 127.0.0.1:3000  
    mode http
    timeout client 120s

    option forwardfor
    # Fake connection:close, required in this setup.
    option http-server-close
    option http-pretend-keepalive

    acl is_engineio path_beg /engine.io

    use_backend socket-servers if is_engineio
    default_backend http-servers


backend http-servers  
    balance roundrobin
    option httpclose
    option forwardfor

    # Roundrobin switching
    server node-1 127.0.0.1:4000 check
    server node-2 127.0.0.1:4001 check


backend socket-servers  
    timeout server  120s
    balance leastconn

    # based on cookie set in header
    # haproxy will add the cookies for us
    cookie SRVNAME insert
    server node-1 127.0.0.1:5000 cookie S1 check
    server node-2 127.0.0.1:5001 cookie S2 check

`

Notes

acl is_engineio path_beg /engine.io

use_backend socket-servers if is_engineio
default_backend http-servers

The above instructs haproxy to make a distinction for regular HTTP requests and socket related requests based on the /engine.io path of the request.

balance roundrobin

For the httpServers, we use a roundrobin strategy to distribute requests to different servers. Basically, we alternate the servers to send a requests to.

server node-1 127.0.0.1:4000 check
server node-2 127.0.0.1:4001 check

We use two httpServers, listening on ports 4000 and 4001.

balance leastconn

We use a least connection strategy for engine.io traffic. This is better for long lasting connections. Haproxy selects the server with the least amount of connections to route new connections to (if no earlier connection from that client was made).

cookie SRVNAME insert

This part is an important directive to make engine.io work. We use a technique called sticky sessions to route all request from the one client to the same server. It instructs haproxy to issue a cookie for each connection to differentiate servers. It will take this cookie into account to route incoming requests from a client that already made requests before to the same socketServer.

server node-1 127.0.0.1:5000 cookie S1 check
server node-2 127.0.0.1:5001 cookie S2 check

Our socketServers listen on port 5000 and 5001.

Resources

• engine.io
• haproxy
• haproxy documentation
• sock.js example haproxy config

What user information to store in the session and what not?

It's best to keep the session information small and only attach user information you actually need (note: some user info should be kept - like for instance the user ID, otherwise passport cannot use its Session Strategy).

However, if you use the deserializeUser method to go and load the user from the db based on the user ID attached to the session, it's better to store the entire user object in the session. This will prevent a roundtrip to the database on every request just to fetch user information.

How to split up passportjs configuration between multiple files?

In the example, all password configuration and Local Strategy definition was specified in the main app.js file.

The passport instance we get back from require('passport') is a singleton. So we can just configure express to use the passport middleware in app.js while configuring passport in another file. They all need to require('passport').

There's no need to pass the password instance around.

What if my form elements are named email and password instead of username and password?

Configure which values passport should use from the request body by the options object passed while configuring the Local Strategy.

passport.use(new LocalStrategy(
    {
        usernameField: 'email',
        passwordField: 'password'   
    },
    function verify(email, password, done) {

        findByEmail(email, function(err, user) {
            if (err) return done(err);
            if (!user) return done(null, false);
            passwordHash.compare(password, user.password, function(err, res) {
                if (err) return done(err);
                if (!res) return done(null, false);
                done(null, user);
            });
        });
    }
));

What if I don't like how passport.authenicate redirects the user but want to respond with a JSON response?

Don't use passport.authenticate as middleware but invoke it directly in the request handler. We need to manually call login for this to work.

app.post('/login', function handleLocalAuthentication(req, res, next) {

    passport.authenticate('local', function(err, user, info) {
        if (err) return next(err);
        if (!user) {
            return res.json(403, {
                message: "no user found"
            });
        }

        // Manually establish the session...
        req.login(user, function(err) {
            if (err) return next(err);
            return res.json({
                message: 'user authenticated',
            });
        });

    })(req, res, next);
};

How to restrict access to certain pages?

Just define your own middleware to be invoked on certain routes to restrict access.

// Define it
module.exports = function restrict(req, res, next) {
    if (req.isUnAuthenticated()) return req.json(403, {message: 'Access denied, please log in'});

    next();
}

Use it when setting up your routes.

// Use the restrict middleware
app.get('/route-with-restricted-access', restrict, function(res, res, next) {
    // Handle request...
});

If the user object contains role information, we could make additional checks on which role a user has and depending on that restrict access.

It is flexible in the sense that it allows for different authentication strategies (think via Twitter, via our own user database - installed via separate modules that can be combined) and it allows us to specify any route or output during authentication.

The Local Strategy allows us to authenticate users by looking up their data in the app's database. It has some great examples how to use it.

In this post, we walk through the authentication flow, the next post discusses some partical use cases using passportjs.

Different parts in using passport.js

There are three main parts in using passport.js:

• Requiring the module and using its passport.initialize() and passport.session() middleware with express.
• Configuring passport with at least one Strategy and setting up passport's serializeUser and deserializeUser methods.
• Specifying a route which uses the passport.authenticate middleware to actually authenticate a user.

The example clearly demonstrates the different items. We wont go over it again.

Authentication request flow

With the tree parts configured as in the example, the following happens when a user tries the authenticate via the /login route:

1. When the user submits the login form, a POST request to /login is made resulting in the execution of the passport.authenticate middleware we've set up.
2. As the authenticate middleware for that route is configured to handle the local strategy, passport will invoke our implementation of the local strategy.
3. Passport takes the req.body.username and req.body.password and passes it to our verification function in the local strategy.
4. Now we do our thing: loading the user from the database and checking if the password given matches the one in the database.
5. In case of an Error interacting with our database, we need to invoke done(err). When we cannot find the user or the passwords do not watch, we invoke done(null, false). If everything went fine and we want the user to login we invoke done(null, user).
6. Calling done will make the flow jump back into passport.authenticate. It's passed the error, user and additional info object (if defined).
7. If the user was passed, the middleware will call req.login (a passport function attached to the request).
8. This will call our passport.serializeUser method we've defined earlier. This method can access the user object we passed back to the middleware. It's its job to determine what data from the user object should be stored in the session. The result of the serializeUser method is attached to the session as req.session.passport.user = { // our serialised user object // }.
9. The result is also attached to the request as req.user.
10. Once done, our requestHandler is invoked. In the example the user is redirected to the homepage.

Subsequent authenticated requests flow

On subsequent request, the following occurs:

1. Express loads the session data and attaches it to the req. As passport stores the serialised user in the session, the serialised user object can be found at req.session.passport.user.
2. The general passport middleware we setup (passport.initialize) is invoked on the request, it finds the passport.user attached to the session. If is doesn't (user is not yet authenticated) it creates it like req.passport.user = {}.
3. Next, passport.session is invoked. This middleware is a Passport Strategy invoked on every request. If it finds a serialised user object in the session, it will consider this request authenticated.
4. The passport.session middleware calls passport.deserializeUser we've setup. Attaching the loaded user object to the request as req.user.

Summary passport methods and middleware

• passport.initialize middleware is invoked on every request. It ensures the session contains a passport.user object, which may be empty.
• passport.session middleware is a Passport Strategy which will load the user object onto req.user if a serialised user object was found in the server.
• passport.deserializeUser is invoked on every request by passport.session. It enables us to load additional user information on every request. This user object is attached to the request as req.user making it accessible in our request handling.
• Our Local Strategy is only invoked on the route which uses the passport.authenticate middleware.
• Only during this authentication passport.serializeUser is invoked allowing us the specify what user information should be stored in the session.

Overview passport methods attached to the request

To finish an overview of passport methods accessible within request handlers:

• req.login()
• req.logout()
• req.isAuthenticated()
• req.isUnAuthenticated()

Drupal 8 will ship with backbone.js and although backbone is just a tiny library that makes it much easier to structure JavaScript code, it does make the code more complex. It simplifies maintainability but at the same time adds a layer of complexity by adding new abstractions and rules about organising JavaScript code. It is easy to work with as long as we have an understanding of these rules and concepts. To prevent it being "a pain in the #!$", we should get to know Backbone.

As I'm scheduled first thing Sunday morning, I hope people make it that early...

Thanks to Sven Decabooter for recording the talk and Wunderkraut for hosting the event.

Recording (in Dutch) and more info can be found on the drupal.be community website.

The talk is a practical d3.js introduction to teach some of d3's fundamentals such as data-joins, scales, axis, labels, ticks, animations...

We started off with a plain SVG representing a chart, refine it, in each iteration touching a new topic to actually update the chart (animate bars and scale) every x minutes.

Take a look at the presentation slides and the demo code.

Resources

• Presentation slides
• Presentation demo code
• Fronteers announcement

It's all about Backbone.js fundamentals with models, collections, views and their interaction (change event - rendering), to really understand what's going and how it helps manage JavaScript application complexity.

Checkout the presentation slides and demo code.

We gave a practical introduction to using Grunt.js. Once the basics (installing, using) were adressed, we took on some more advanced, in depth topics such as tasks, "magic" config attributes and project scaffolding.

Checkout the presentation slides and the demo code.

We ended up creating a backbone.js application to display the slides touching on different topics.

Some of the challenges

• Display the chart axis on page load, but only start displaying the chart's content (graphs) when within the viewport.
• Don't start showing the chart's content when the visitor is scrolling very fast over them.
• Initially, the charts had a fixed width. We ended up making the charts responsive by adapting to the available width.
• The visitor can scroll to specific slides using the menu.
• Create a static one pager with a JavaScript application to make everything interactive.
• Make parts of the d3.js charts reusable since we created several of them.

Some of the tools used

• Backbone.js: to structure the application and keep us sane
• D3.js: to create the different charts
• jQuery waypoints: to decide when to display the chart's contents and figure out which menu link to activate
• Gruntjs: to help us build the endresult, which is basically one static file
• require.js: to load the different JavaScript files and divide the JavaScript application in different modules

Checkout the endresult.

I have it already set up to send emails (one of the default actions), but I wanted it to send me a text message every time an IP gets banned.

Fail2ban does not ship with such an action. Fortunately, it's not hard to create one.

How to extend fail2ban with custom actions?

It's easy to extend Fail2ban with custom actions. You only need to do two things:
1. Create a new action in the /etc/fail2/ban/actions.d directory
2. Configure jail.local to use that action

Create new action in actions.d

The easiest way to create a new action is to copy dummy.conf to new-action.conf and edit it. You'll find the different "hooks" you can use to execute your commands. Variables are passed via "<variable>" syntax.

Below you'll find my sms.conf.

#
# Author: Toon Ketels
#
# $Revision$
#

[Definition]

# Option:  actionstart
# Notes.:  command executed once at the start of Fail2Ban.
# Values:  CMD
#
actionstart = /home/all/scripts/fail2ban-sms.sh start

# Option:  actionstop
# Notes.:  command executed once at the end of Fail2Ban
# Values:  CMD
#
actionstop = /home/all/scripts/fail2ban-sms.sh stop

# Option:  actioncheck
# Notes.:  command executed once before each actionban command
# Values:  CMD
#
actioncheck =

# Option:  actionban
# Notes.:  command executed when banning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    <ip>  IP address
#          <failures>  number of failures
#          <time>  unix timestamp of the ban time
# Values:  CMD
#
actionban = /home/all/scripts/fail2ban-sms.sh ban <ip>

# Option:  actionunban
# Notes.:  command executed when unbanning an IP. Take care that the
#          command is executed with Fail2Ban user rights.
# Tags:    <ip>  IP address
#          <failures>  number of failures
#          <time>  unix timestamp of the ban time
# Values:  CMD
#
actionunban = /home/all/scripts/fail2ban-sms.sh unban <ip>

[Init]

init = 'Custom startup message

Above you see we don't actually send text messages directly from within this file, but invoke the script located at /home/all/scripts/fail2ban-sms.sh. We use the <ip> variable to be send in the text message and pass it as an argument to the script.

Using scripts makes it easier to change the texting implementation later on (or when we would like to change provider).

Before we look into the text messaging script, let's activate the command.

Config fail.local to execute action

Configure Fail2ban by copying jail.conf to jail.local and edit the file. We want texting whenever someone tries to bruteforce ssh. So we add "sms" to the list of actions in the ssh section like below.

#
# in /etc/fail2ban/jail.local.
#
# Optionally you may override any other parameter (e.g. banaction,
# action, port, logpath, etc) in that section within jail.local

[ssh]

enabled  = true
port     = ssh
filter   = sshd
logpath  = /var/log/auth.log
maxretry = 6
action = mail-whois[name=SSH, dest=my.email@gmail.com]
         sms

Texting using twilio

Twilio's API makes it easy to send sms's. Just POST to their api to text. Below you find the script used to perform the request to their API.

#!/bin/bash

# Sends text messages using twilio api
# to alert webmaster of banning.
#
# Requires one argument, one of the following:
#  start
#  stop
#  ban
#  unban
#
# Optional second argument: IP for ban/unban



# Include file with the following content:
#   sid=<twilio account sid>
#   token=<twilio auth token>
#   from=<phone number>
#   to=<phone number>
source secret.conf



# Display usage information
function show_usage {
  echo "Usage: $0 action <ip>"
  echo "Where action is start, stop, ban, unban"
  echo "and ip is optional passed to ban, unban"
  exit
}



# Actually send sms
# Expects the sms content (body) to be passed
# as argument.
function send_sms {
  /usr/bin/curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$sid/SMS/Messages.json" -d "From=$from" -d "To=$to" -d "Body=$1" -u "$sid:$token" >> '/home/all/log/fail2ban-sms.log'    
  exit
}



# Check for script arguments
if [ $# -lt 1 ]
then
  show_usage
fi



# Take action depending on argument
if [ "$1" = 'start' ]
then
  message='Fail2ban+just+started.'
  send_sms $message
elif [ "$1" = 'stop' ]
then
  message='Fail2ban+just+stopped.'
  send_sms $message
elif [ "$1" = 'ban' ]
then
  message=$([ "$2" != '' ] && echo "Fail2ban+just+banned+$2" || echo 'Fail2ban+just+banned+an+ip.' )
  send_sms $message
elif [ "$1" = 'unban' ]
then
  message=$([ "$2" != '' ] && echo "Fail2ban+just+unbanned+$2" || echo "Fail2ban+just+unbanned+an+ip." )
  send_sms $message
else
  show_usage

The script expects a secret.conf in the same directory to read the Twilio authentication data and phone numbers from. The output of the requests are appended to a logfile in /home/all/log/fail2ban-sms.log.

Repo

You find the config file and script in github repo.

Resources

• www.fail2ban.org
• www.twilio.com
• github.com/toonketels/fail2ban-sms
• blog.redbranch.net/2013/02/28/fail2ban-custom-action