HAProxyCTL

This is a simple wrapper to make life with HAProxy a little more convenient.

Acts as an init script for start, stop, reload, restart, etc
Leverages 'socket' to enable and disable servers on the fly
Formats server weight and backends in a readable way
Provides Nagios and Cloudkick health checks
chkconfig/service-able for Redhat folk

Here is a presentation about it. Hit space to advance slides.

Installation

On most UNIX, assuming HAProxy is in the $PATH:

git clone git@github.com:flores/haproxyctl.git
ln -s haproxyctl/haproxyctl /etc/init.d/haproxyctl

For chkconfig/RedHat/Centos, add:

chkconfig --add haproxyctl

Or if have RubyGems, just gem install it!

gem install haproxyctl

Or if you are on Debian, just install haproxy with apt-get!

apt-get install haproxyctl

There is also an HAProxy source installation script. This installs not only the steps above but also HAProxy itself.

Options

# ./haproxyctl help
usage: ./haproxyctl 
  where argument can be:
    start: start haproxy unless it is already running
    stop: stop an existing haproxy
    restart: immediately shutdown and restart
    reload: gracefully terminate existing connections, reload /etc/haproxy/haproxy.cfg
    status: is haproxy running?  on what ports per lsof?
    configcheck: check /etc/haproxy/haproxy.cfg
    nagios: nagios-friendly status for running process and listener
    cloudkick: cloudkick.com-friendly status and metric for connected users
    show health: show status of all frontends and backend servers
    show backends: show status of backend pools of servers
    enable all : re-enable a server previously in maint mode on multiple backends
    disable all : disable a server from every backend it exists
    enable all EXCEPT : like 'enable all', but re-enables every backend except for 
    disable all EXCEPT : like 'disable all', but disables every backend except for 
    clear counters: clear max statistics counters (add 'all' for all counters)
    help: this message
    prompt: toggle interactive mode with prompt
    quit: disconnect
    show info: report information about the running process
    show stat [counter...]: report counters for each proxy and server
    show errors: report last request and response errors for each proxy
    show sess [id]: report the list of current sessions or dump this session
    get weight: report a server's current weight
    set weight: change a server's weight
    set timeout: change a timeout setting
    disable server: set a server in maintenance mode
    enable server: re-enable a server that was previously in maintenance mode

Examples

Status check

  ./haproxyctl status
  haproxy is running on pid 23162.
  these ports are used and guys are connected:
  173.255.194.115:www->98.154.245.132:52025 (ESTABLISHED)
  173.255.194.115:www->97.89.32.126:52043 (ESTABLISHED)
  *:www (LISTEN)
  *:53093 
  173.255.194.115:www->83.39.69.106:19338 (ESTABLISHED)

Errors to the backend servers

  ./haproxyctl "show errors"
  [04/Feb/2011:21:05:59.542] frontend http (#1): invalid request
    src 209.59.188.205, session #39574, backend  (#-1), server  (#-1)
    request length 125 bytes, error at position 27:
 
    00000  GET /logs/images/stuff/someurl
    00070+  HTTP/1.1\r\n
    00081  Host: wet.biggiantnerds.com\r\n
    00110  Accept: */*\r\n
    00123  \r\n

Human readable health check

  ./haproxyctl "show health"
    pxname      svname       status  weight
  http        FRONTEND                  OPEN       
  sinatra     sinatra_downoi            DOWN    1  
  sinatra     sinatra_rindica           DOWN    1  
  sinatra     sinatra_guinea            UP      1  
  sinatra     BACKEND                   UP      1  
  ei          guinea                    UP      1  
  ei          belem                     UP      1  
  ei          BACKEND                   UP      1  
  drop        guinea                    UP      1  
  drop        belem                     UP      1  
  drop        BACKEND                   UP      1  
  apache      guinea                    UP      1  
  apache      belem                     UP      1  
  apache      BACKEND                   UP      1  
  static      ngnix_downoi              UP      1  
  static      ngnix_petite              UP      1  
  static      ngnix_rindica             UP      1  
  static      nginx_stellatus           UP      1  
  static      nginx_belem               UP      1  
  static      nginx_petite              DOWN    1  
  static      apache_guinea             UP      1  
  static      BACKEND                   UP      6  
  ssh         localhost                 UP      1  
  ssh         BACKEND                   UP      1  

  ./haproxyctl "show backends"
  contact     BACKEND                   UP      1
  alpha       BACKEND                   DOWN    0
  sinatra     BACKEND                   DOWN    0
  python      BACKEND                   UP      1
  mobile      BACKEND                   DOWN    0
  ei          BACKEND                   UP      1
  showoff     BACKEND                   UP      1
  drop        BACKEND                   UP      1
  cheap       BACKEND                   UP      1
  apache      BACKEND                   UP      1
  static      BACKEND                   UP      1
  ssh         BACKEND                   UP      1

Disable servers on the fly

  ./haproxyctl "disable server static/nginx_belem"
  
  ./haproxyctl "show health" |grep nginx_belem
  static      nginx_belem               MAINT   1

Graceful reloads

  ./haproxyctl reload
  gracefully stopping connections on pid 23162...
  checking if connections still alive on 23162...
  reloaded haproxy on pid 1119

Cloudkick/Nagios checks with graph-friendly output for queue size, total connections, etc

  ./haproxyctl cloudkick    
  status ok haproxy is running
  metric connections int 12
  metric http_FRONTEND_request_rate int 45
  metric http_FRONTEND_health_check_duration int 45
  metric sinatra_sinatra_guinea_health_check_duration int 4
  metric sinatra_BACKEND_health_check_duration int 4
  metric mobile_sinatra_mobile_health_check_duration int 2
  metric mobile_BACKEND_health_check_duration int 2
  metric ei_guinea_health_check_duration int 4
  metric ei_BACKEND_health_check_duration int 4
  metric drop_guinea_total_requests gauge 1
  metric drop_guinea_health_check_duration int 6
  metric drop_BACKEND_total_requests gauge 1
  metric drop_BACKEND_health_check_duration int 6
  metric apache_guinea_health_check_duration int 41
  metric apache_BACKEND_health_check_duration int 41
  metric static_ngnix_downoi_total_requests gauge 472
  metric static_ngnix_downoi_health_check_duration int 7
  metric static_ngnix_petite_total_requests gauge 475
  metric static_ngnix_petite_health_check_duration int 8
  metric static_ngnix_rindica_total_requests gauge 457
  metric static_ngnix_rindica_health_check_duration int 8
  metric static_nginx_stellatus_total_requests gauge 470
  metric static_nginx_stellatus_health_check_duration int 7
  metric static_nginx_belem_total_requests gauge 460
  metric static_nginx_belem_health_check_duration int 8
  metric static_apache_guinea_total_requests gauge 449
  metric static_apache_guinea_health_check_duration int 14
  metric static_BACKEND_total_requests gauge 2783
  metric static_BACKEND_health_check_duration int 45

does normal things like checks if a process is running before starting it...

  ./haproxyctl start    
  ./haproxyctl:35: haproxy is already running on pid 20317! (RuntimeError)
  
  ./haproxyctl restart
  stopping existing haproxy on pid 20317...
  waiting a ms...
  checking if haproxy is still running...
  starting haproxy...
  done.  running on pid 20348

keeps all the regular UNIX socket stuff

  ./haproxyctl "show stat"
  pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq,dresp,ereq,econ,eresp,wretr,wredis,status,weight,act,bck,chkfail,chkdown,lastchg,downtime,qlimit,pid,iid,sid,throttle,lbtot,tracked,type,rate,rate_lim,rate_max,check_status,check_code,check_duration,hrsp_1xx,hrsp_2xx,hrsp_3xx,hrsp_4xx,hrsp_5xx,hrsp_other,hanafail,req_rate,req_rate_max,req_tot,cli_abrt,srv_abrt,
  http,FRONTEND,,,3,82,2000,39585,47067637,12818945246,0,0,1465,,,,,OPEN,,,,,,,,,1,1,0,,,,0,0,0,59,,,,0,91460,13125,4115,305,73,,0,131,109078,,,
  sinatra,sinatra_downoi,0,0,0,1,,791,452469,2258353,,0,,0,0,0,0,UP,1,1,0,60,13,304106,59545,,1,2,1,,791,,2,0,,1,L4OK,,46,0,736,0,40,15,0,0,,,,0,0,
  sinatra,sinatra_rindica,0,0,0,1,,795,450488,2333534,,0,,0,0,3,1,UP,1,1,0,68,10,347679,52849,,1,2,2,,792,,2,0,,1,L4OK,,46,0,753,0,28,10,0,0,,,,0,0,
  sinatra,sinatra_guinea,0,0,0,7,,638,360994,1046343,,0,,0,258,1,0,UP,1,1,0,4,4,1892969,72241,,1,2,3,,637,,2,0,,3,L4OK,,0,0,317,0,13,11,0,0,,,,0,0,
  sinatra,BACKEND,0,0,0,7,0,2219,1263951,5638230,0,0,,0,299,4,1,UP,3,3,0,,0,2144680,0,,1,2,0,,2220,,1,0,,3,,,,0,1806,0,81,291,41,,,,,0,0,
  ei,guinea,0,0,0,4,,3514,2067456,68408884,,0,,0,0,0,0,UP,1,1,0,6,1,2142278,70,,1,3,1,,3514,,2,0,,11,L4OK,,0,0,3060,323,131,0,0,0,,,,3,0,
  ei,belem,0,0,0,0,,0,0,0,,0,,0,0,0,0,UP,1,0,1,28,7,259858,1274,,1,3,2,,0,,2,0,,0,L4OK,,43,0,0,0,0,0,0,0,,,,0,0,
  ei,BACKEND,0,0,0,4,0,3514,2067456,68408884,0,0,,0,0,0,0,UP,1,1,1,,0,2144680,0,,1,3,0,,3514,,1,0,,11,,,,0,3060,323,131,0,0,,,,,3,0,
  drop,guinea,0,0,0,2,,1042,634412,15327695,,0,,0,0,0,0,UP,1,1,0,5,1,2142277,70,,1,4,1,,1042,,2,0,,5,L4OK,,0,0,935,28,79,0,0,0,,,,2,0,
  drop,belem,0,0,0,0,,0,0,0,,0,,0,0,0,0,UP,1,0,1,42,7,259855,958,,1,4,2,,0,,2,0,,0,L4OK,,44,0,0,0,0,0,0,0,,,,0,0,
  drop,BACKEND,0,0,0,2,0,1042,634412,15327695,0,0,,0,0,0,0,UP,1,1,1,,0,2144680,0,,1,4,0,,1042,,1,0,,5,,,,0,935,28,79,0,0,,,,,2,0,
  apache,guinea,0,0,0,3,,3781,3733003,19959026,,0,,0,0,0,0,UP,1,1,0,4,1,2142276,70,,1,5,1,,3781,,2,0,,5,L4OK,,0,0,3267,304,208,2,0,0,,,,2,0,
  apache,belem,0,0,0,1,,1,379,528,,0,,0,0,0,0,UP,1,0,1,41,7,259854,1023,,1,5,2,,1,,2,0,,1,L4OK,,43,0,0,0,1,0,0,0,,,,0,0,
  apache,BACKEND,0,0,0,3,0,3782,3733382,19959554,0,0,,0,0,0,0,UP,1,1,1,,0,2144680,0,,1,5,0,,3782,,1,0,,5,,,,0,3267,304,209,2,0,,,,,2,0,
  static,ngnix_downoi,0,0,0,10,,12665,4970818,1883260969,,0,,0,4,25,5,UP,1,1,0,72,10,303928,61648,,1,6,1,,12640,,2,0,,10,L4OK,,46,0,10671,1656,307,0,0,0,,,,1167,4,
  static,ngnix_petite,0,0,0,10,,13052,5141468,2033386644,,0,,1,5,13,3,UP,1,1,0,63,6,347401,11776,,1,6,2,,13039,,2,0,,10,L4OK,,46,0,10988,1694,352,0,0,0,,,,1223,4,
  static,ngnix_rindica,0,0,0,10,,12736,5007655,2002399557,,0,,0,8,20,5,UP,1,1,0,64,10,347499,55375,,1,6,3,,12716,,2,0,,10,L4OK,,45,0,10736,1649,321,0,0,0,,,,1146,3,
  static,nginx_stellatus,0,0,0,10,,15142,6017327,2194578425,,0,,0,7,0,0,UP,1,1,0,8,1,1555595,786,,1,6,4,,15142,,2,0,,10,L4OK,,42,0,12932,1844,364,0,0,0,,,,1253,8,
  static,nginx_belem,0,0,0,10,,15227,6075157,2231761586,,0,,0,5,1,0,UP,1,1,0,10,1,1555573,787,,1,6,5,,15226,,2,0,,12,L4OK,,44,0,12981,1882,362,0,0,0,,,,1227,4,
  static,nginx_petite,0,0,0,0,,0,0,0,,0,,0,0,0,0,DOWN,1,1,0,0,1,2144610,2144610,,1,6,6,,0,,2,0,,0,L4CON,,21000,0,0,0,0,0,0,0,,,,0,0,
  static,apache_guinea,0,0,0,10,,24091,9895320,2263895160,,0,,0,0,0,0,UP,1,1,0,2,0,2144680,0,,1,6,7,,24091,,2,0,,100,L4OK,,0,0,20593,3038,459,0,0,0,,,,1241,0,
  static,BACKEND,0,0,0,60,0,92841,37107745,12609282341,0,0,,1,29,59,13,UP,6,6,0,,0,2144680,0,,1,6,0,,92854,,1,0,,131,,,,0,78901,11763,2165,12,0,,,,,7257,23,
  ssh,localhost,0,0,0,3,,122,54524,291662,,0,,0,0,0,0,UP,1,1,0,0,0,2144680,0,,1,7,1,,122,,2,0,,10,L4OK,,0,0,121,0,1,0,0,0,,,,0,0,
  ssh,BACKEND,0,0,0,3,0,122,54524,291662,0,0,,0,0,0,0,UP,1,1,0,,0,2144680,0,,1,7,0,,122,,1,0,,10,,,,0,121,0,1,0,0,,,,,0,0,

Extends stat command to print only counters supplied as arguments

  ./haproxyctl "show stat qcur qmax"
  http,FRONTEND,,
  sinatra,sinatra_downoi,0,0
  sinatra,sinatra_rindica,0,0
  sinatra,sinatra_guinea,0,0
  sinatra,BACKEND,0,0
  ei,guinea,0,0
  ei,belem,0,0
  ei,BACKEND,0,0
  drop,guinea,0,0
  drop,belem,0,0
  drop,BACKEND,0,0
  apache,guinea,0,0
  apache,belem,0,0
  apache,BACKEND,0,0
  static,ngnix_downoi,0,0
  static,ngnix_petite,0,0
  static,ngnix_rindica,0,0
  static,nginx_stellatus,0,0
  static,nginx_belem,0,0
  static,nginx_petite,0,0
  static,apache_guinea,0,0
  static,BACKEND,0,0
  ssh,localhost,0,0
  ssh,BACKEND,0,0

Enable or disable a target server from every backend it appears.

  ./haproxyctl "show health"
  # pxname        svname               status  weight
  http            FRONTEND             OPEN       
  sinatra         sinatra_downoi       DOWN    1  
  sinatra         sinatra_rindica      DOWN    1  
  sinatra         sinatra_guinea       UP      1  
  sinatra         BACKEND              UP      1  
  ei              guinea               UP      1  
  ei              BACKEND              UP      1  
  drop            guinea               UP      1  
  drop            BACKEND              UP      1  
  apache          guinea               UP      1  
  apache          BACKEND              UP      1  
  static          ngnix_downoi         UP      1  
  static          ngnix_petite         UP      1  
  static          ngnix_rindica        UP      1  
  static          nginx_stellatus      UP      1  
  static          nginx_belem          UP      1  
  static          nginx_petite         MAINT   1  
  static          apache_guinea        UP      1  
  static          BACKEND              UP      6  
  ssh             localhost            UP      1  
  ssh             BACKEND              UP      1  
  
                                                 
  ./haproxyctl "disable all guinea"
  ./haproxyctl "show health"
    pxname        svname               status  weight
  http            FRONTEND             OPEN       
  sinatra         sinatra_downoi       DOWN    1  
  sinatra         sinatra_rindica      DOWN    1  
  sinatra         sinatra_guinea       UP      1  
  sinatra         BACKEND              UP      1  
  ei              guinea               MAINT   1  
  ei              BACKEND              DOWN    0  
  drop            guinea               MAINT   1  
  drop            BACKEND              DOWN    0  
  apache          guinea               MAINT   1  
  apache          BACKEND              DOWN    0  
  static          ngnix_downoi         UP      1  
  static          ngnix_petite         UP      1  
  static          ngnix_rindica        UP      1  
  static          nginx_stellatus      UP      1  
  static          nginx_belem          UP      1  
  static          nginx_petite         UP      1  
  static          apache_guinea        UP      1  
  static          BACKEND              UP      1  
  ssh             localhost            UP      1  
  ssh             BACKEND              UP      1

Has an EXCEPT flag, too

  ./haproxyctl "enable all EXCEPT apache_guinea"
  ./haproxyctl "show health"
    pxname        svname               status  weight
  http            FRONTEND             OPEN       
  sinatra         sinatra_downoi       DOWN    1  
  sinatra         sinatra_rindica      DOWN    1  
  sinatra         sinatra_guinea       UP      1  
  sinatra         BACKEND              UP      1  
  ei              guinea               UP      1  
  ei              BACKEND              UP      1  
  drop            guinea               UP      1  
  drop            BACKEND              UP      1  
  apache          guinea               UP      1  
  apache          BACKEND              UP      1  
  static          ngnix_downoi         UP 1/2  1  
  static          ngnix_petite         UP 1/2  1  
  static          ngnix_rindica        UP 1/2  1  
  static          nginx_stellatus      UP 1/2  1  
  static          nginx_belem          UP 1/2  1  
  static          nginx_petite         UP 1/2  1  
  static          apache_guinea        UP      1  
  static          BACKEND              UP      7  
  ssh             localhost            UP      1  
  ssh             BACKEND              UP      1

Contributors

flores aka flores
Scott Gonyea aka sgonyea
Ben Lovett aka blovett
John A. Barbuto aka jbarbuto
Till Klampaeckel aka till
Erik Osterman aka osterman
Martin Hald aka mhald
deniedboarding
Aaron Blew aka blewa
Nick Griffiths aka nicobrevin
Florian Holzhauer aka fh
Jonas Genannt aka hggh
Grant Shively aka gshively11

Non-current HAProxy versions

Be aware that HAProxy below version 1.4 does not support many of the options of haproxyctl.

License

This code is released under the MIT License. You should feel free to do whatever you want with it.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

HAProxyCTL

Installation

Options

Examples

Status check

Errors to the backend servers

Human readable health check

Disable servers on the fly

Graceful reloads

Cloudkick/Nagios checks with graph-friendly output for queue size, total connections, etc

does normal things like checks if a process is running before starting it...

keeps all the regular UNIX socket stuff

Extends stat command to print only counters supplied as arguments

Enable or disable a target server from every backend it appears.

Has an EXCEPT flag, too

Contributors

Non-current HAProxy versions

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

HAProxyCTL

Installation

Options

Examples

Status check

Errors to the backend servers

Human readable health check

Disable servers on the fly

Graceful reloads

Cloudkick/Nagios checks with graph-friendly output for queue size, total connections, etc

does normal things like checks if a process is running before starting it...

keeps all the regular UNIX socket stuff

Extends stat command to print only counters supplied as arguments

Enable or disable a target server from every backend it appears.

Has an EXCEPT flag, too

Contributors

Non-current HAProxy versions

License