Tag: github

Adding Versioning to an Existing MkDocs Site

IXP Manager uses MkDocs with Material to power its professional documentation site at https://docs.ixpmanager.org/, which is hosted via GitHub pages. This all sounds convoluted, but when set up, it’s really simple, and we have this documented here.

We are now close to releasing IXP Manager v7, and it has become apparent that the single documentation site is suboptimal and confusing for people who have not upgraded but are reading about newer features. The best solution for this is to introduce major.minor versioning on the documentation site.

Material supports versioning via another tool called mike. For a new site, this is quite easy to set up and run, but we had to do the following for an existing site.

Quick side note: we are using a Python venv for mkdocs, mike, etc. and not installing system wide. One thing to watch out for is that mike calls mkdocs but this may not be in your path. This can be solved by updating the PATH environment variable or running mike as follows:

PATH=./venv/bin:$PATH mike deploy --push --update-aliases 7.0 dev
  1. Install mike per its and Material’s documentation.
  2. Delete the old documentation site: mike delete --all
  3. Deploy your current docs as the latest version: mike deploy --push --update-aliases 6.4 latest
  4. Deploy the docs you are working on for the upcoming version as the dev tag: mike deploy --push --update-aliases 7.0 dev
  5. Set the default docs: mike set-default --push latest
  6. We were using a custom CNAME for Github pages and a custom 404 page. These would have been removed with step (2) above but are both available in your documentation’s Githib repo under the gh-pages branch history. To restore these you need to place them back in the root folder of the gh-pages branch:
git checkout gh-pages
echo docs.ixpmanager.org >CNAME
wget https://raw.githubusercontent.com/$org/$repo/$hash/404.html
git add CNAME 404.html
git commit -am 'add back cname and 404'
git push

Useful Git Links

A live document updated over time to collect various Git related links that I find useful.

Official Documents

My Own Documents

Third Party Documents

Nagios Plugin to Check Extreme Networks Devices

Over at INEX we’ve embarked on a forklift upgrade of the primary peering LAN using Extreme Networks Summit x670’s and x460’s. As usual, we need to monitor these 24/7 and we have just written a new Extreme Networks chassis monitoring script which should work with most Extreme devices.

It will check and generate alerts on the following items:

  • a warning if the device was recently rebooted;
  • a warning / critical if any found temperature sensors are in a non-normal state;
  • a warning / critical if any found fans are in a non-normal state;
  • a warning / critical if any found PSUs are in a non-normal state (or missing);
  • a warning / critical if the 5 sec CPU utilisation is above set thresholds;
  • a warning / critical if the memory utilisation is above set thresholds.

You’ll find the script in this Github repository: barryo/nagios-plugins.

A some verbose output follows:

./check_chassis_extreme.php -c  -h 10.11.12.13 -v 
 
CPU: 5sec - 4% 
Last reboot: 4007.7666666667 minutes ago 
Uptime: 2.8 days. 
PSU: 1 - presentOK (Serial: 1429W-xxxxx; Source: ac) 
PSU: 2 - presentOK (Serial: 1429W-xxxxx; Source: ac) 
Fan: 101 - OK (4388 RPM) 
Fan: 102 - OK (9273 RPM) 
Fan: 103 - OK (4428 RPM) 
Fan: 104 - OK (9273 RPM) 
Fan: 105 - OK (4551 RPM) 
Fan: 106 - OK (9452 RPM) 
Temp: 39'C 
Over temp alert: NO 
Memory used in slot 1: 29% 
OK - CPU: 5sec - 4%. Uptime: 2.8 days.  PSUs: 1 - presentOK; 
  2 - presentOK;. Overall system power state: redundant power 
  available. Fans: [101 - OK (4388 RPM)]; [102 - OK (9273 RPM)];
  [103 - OK (4428 RPM)]; [104 - OK (9273 RPM)]; [105 - OK (4551 
  RPM)]; [106 - OK (9452 RPM)];. Temp: 39'C. 
  Memory (slot:usage%): 1:29%.

Doctrine2 Service Provider for Laravel 4

I’ve just released a Laravel 4 package which contains a service provider to the Doctine2 entity manager and the Doctrine2 cache. These are made available via facades named D2EM and D2Cache respectively.

Currently it uses the XML schema method for defining entities but this can easily be augmented with the other methods. Also, ArrayCache and MemcacheCache are fully supported caching interfaces. Any other cache that requires no configuration is also supported but some trivial coding will be required for caching backends required configuration.

Combining this with TwigBridge, we have an excellent framework with Laravel 4!

Nagios / Icinga Alerts via Pushover

I came across Pushover recently which makes it easy to send real-time notifications to your Android and iOS devices. And easy it is. It also allows you to set up applications with logos so that you can have multiple Nagios installations shunting alerts to you via Pushover with each one easily identifiable. After just a day playing with this, it’s much nicer than SMS’.

So, to set up Pushover with Nagios, first register for a free Pushover account. Then create a new application for your Nagios instance. I set the type to Script and also upload a logo. After this, you will be armed with two crucial pieces of information: your application API tokan/key ($APP_KEY) and your user key ($USER_KEY).

To get the notification script, clone this GitHub repository or just down this file – notify-by-pushover.php.

You can test this immediately with:

echo "Test message" | \
    ./notify-by-pushover.php HOST $APP_KEY $USER_KEY RECOVERY OK

The parameters are:

USAGE: notify-by-pushover.php  <$APP_KEY> \
    <$USER_KEY> <NOTIFICATIONTYPE>

Now, set up the new notifications in Nagios / Icinga:

# 'notify-by-pushover-service' command definition
define command{
    command_name notify-by-pushover-service
    command_line /usr/bin/printf "%b" "$NOTIFICATIONTYPE$: \
        $SERVICEDESC$@$HOSTNAME$: $SERVICESTATE$           \
        ($SERVICEOUTPUT$)" |                               \
      /usr/local/nagios-plugins/notify-by-pushover.php     \
        SERVICE $APP_KEY $CONTACTADDRESS1$                 \
        $NOTIFICATIONTYPE$ $SERVICESTATE$
}

# 'notify-by-pushover-host' command definition
define command{
  command_name notify-by-pushover-host
  command_line /usr/bin/printf "%b" "Host '$HOSTALIAS$'    \
        is $HOSTSTATE$: $HOSTOUTPUT$" |                    \
      /usr/local/nagios-plugins/notify-by-pushover.php     \
        HOST $APP_KEY $CONTACTADDRESS1$ $NOTIFICATIONTYPE$ \
        $HOSTSTATE$
}

Then, in your contact definition(s) add / update as follows:

define contact{
  contact_name ...
  ...
  service_notification_commands ...,notify-by-pushover-service
  host_notification_commands ...,notify-by-pushover-host
  address1 $USER_KEY
}

Make sure you break something to test that this works!

NOCtools and OSS_SNMP Get Support for Multiple Spanning Tree (MST) Protocol

NOCtools (a mixed bag collection of tools and utilities for NOC engineers) and OSS_SNMP (a PHP SNMP Library for People Who HATE SNMP, MIBs and OIDs) have just gotten support for Multiple Spanning Tree.

Specifically, OSS_SNMP has two new MIBS (Cisco’s original MST tree which has a lot of deprecated nodes – MIBS\Cisco\MST; and the newer IEEE tree – MIBS\Cisco\SMST). With these, we can, for example, get an array of [instanceID] => instanceName values from a switch by just coding:

$ciscosw = new \OSS_SNMP\SNMP( $ip, $community );
print_r( $ciscosw->useCisco_SMST()->instances() );

NOCtools has the more impressive use cases of these new features. Specifically (and just likes its RSTP/pvrspt functionality), it can:

  • Show MST port roles (root, designated, alternate, etc) for a given (or all) MST instance(s) – this is equivalent to the RSTP version;
  • From a given device, it can crawl all CDP neighbours and create a graph of all devices, their connecting ports and the MST roles of those ports. This is a really useful feature as it means you don’t need to log into multiple switches to get a handle on what links are blocking. See documentation and a sample diagram here.

Synchronising Microsoft Exchange to Another IMAP Server

This post is much less of a detailed how-to but rather some useful links. We were tasked with the job of sync’ing about 1,000 MS Exchange mailboxes to a Dovecot server. This needed to be done via an administrator account on the Exchange end as individual user passwords were not available.

The tool of choice for this is imapsync.  Unfortunately, there is not a single formula that will work for all as it can depend on the Exchange configuration and version as well as the use of domains on the Exchange and ActiveDirectory servers.

To help understand the various combinations of logins for Exchange, I found the following invaluable: Understanding login strings with POP3/IMAP.

Also invaluable is the imapsync FAQ – just search for mentions of Exchange.

In the end, the following worked for me (but your mileage will most definitely vary!):

./imapsync --host1 exchange-server 
    --user1 'domain/adminuser/user' --password1 'admin-password' 
    --authmech1 LOGIN 
    --host2 dovecot-server --user2 user@example.com 
    --password2 userpassword

One key element here is that when logging into Exchange as an individual user I had to use --authmech1 NTLM but if you use this auth method with the above user string, you will always end up logging into the admin’s mailbox, not the user’s. That, at least, was my experience.

Git Web Applications (aka GitHub Alternatives)

I’ve been through the mill with a few of these and it’s a growing list of options. I should start by saying that I love GitHub and use it regularly for a large number of projects (including some of my own, some for my company and some for my customers). The only problem I have with GitHub is that I just haven’t made the jump to trust it with our proprietary code – the primary asset of the company. Particularly after a high profile security breech.

Now, nothing I’ve come across yet comes close to GitHub. But two we use daily have good matching features:

  • Gitorious –  whether they intended it or not, it’s a good clone of GitHub but always a little behind on features. It’s also a Ruby on Rails application and the documentation is getting far better. When we started, it was pretty… shite, to be honest. Installing and upgrading was a pain. They have addressed this with http://getgitorious.com/ which includes a virtual appliance for VirtualBox so you can be up and running in minutes.
  • Atlassian Stash – if you’re a small team (<= 10 users) then this could be for you. Installation is pretty easy, it looks great, is very fast (over HTTP/S, but it’s inbuilt SSH client is extremely slow) and is very easy to use. Pull requests are also done really really well. It’s a full Java webapp so it does require some CPU and memory. For <= 10 users, my definite favorite. Thereafter though it gets expensive – e.g. for up to 25 users you’ll fork out $1,800 / annum. That’s not entirely unaffordable but if you’re using Stash, then you may also be using their other products such as Jira, Confluence, Bamboo, Fisheye and Crucible. Now that adds up to a hefty bill!

One’s I have not tested and so cannot speak authoritively on include:

  • GitLab – Looks like a very interesting alternative.
  • RhodeCode – they say it will “change the way you manage your code”.
  • Gitolite – a quick look at the available information for this definitely puts it in the also ran category. There’s no polish or anything nice to entice one to even try it.
  • Gitosis – in their own words: “Manage git repositories, provide access to them over SSH, with tight access control and not needing shell accounts”. The project appears dead.

 

Nagios Plugin for Checking Backups via rsnapshot

We’ve just added a check_rsnapshot.php script to our nagios-plugins bundle on Github. This script will verify rsnapshot backups via Nagios using a number of checks / tests:

  • minfiles – checks the number of files in a snapshot against a minimum expected number;
  • minsize – checks the size of a snapshot against a minimum expected size;
  • log – parses the rsnapshot log to ensure the most recent runs for each retention period completed successfully;
  • timestamp – checks for files created server side containing a timestamp and thus ensuring snapshots are succeeding;
  • rotation – checks that retention directories are being rotated; and
  • dir-creation – checks that retention directories are being created.

Please see this Github wiki page for more information including instructions.

Try Git In Your Browser

I know, I know. The fourth Git post in a row…

But, in case you missed it or in case you’d like to try Git without installing any software, then checkout http://try.github.com/

Today [GitHub are] launching a unique and easy way, in the format of a Code School interactive course, for new Git and GitHub users to try both the tool and the service without a single bit of software installation.

If you know of a developer, designer, or other knowledge worker that would benefit from using Git but that hasn’t made the leap just yet, send them over to try.github.com when they have a spare 15 minutes.