path: root/docs/fapi.1

.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "FAPI 1"
.TH FAPI 1 "2014-05-27" "fapi 0.8.0" "User Commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
fapi \- A humble command line tool to manage F5 BigIP loadbalancers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Just run
.PP
.Vb 1
\&  fapi \-h
.Ve
.PP
or
.PP
.Vb 2
\&  alias f=fapi
\&  f \-h
.Ve
.PP
because it's shorter to type.
.SH "ABOUT"
.IX Header "ABOUT"
This is a simple command line client to do basic stuff with the iControl F5 \s-1API\s0 
such as:
.PP
.Vb 4
\&  Managing Nodes
\&  Managing Monitors
\&  Managing Pools
\&  Managing Virtual Servers
.Ve
.PP
This is a private programming project programmed in my spare time. Therefore I
didn't bother to put it on a public website and github. Please open bug 
reports, feature requests and pull requests at
<https://github.com/rantanplan/fapi>.
.PP
\&\fB\s-1CAUTION:\s0 This script has been tested on Debian GNU/Linux Wheezy only.\fR
.SH "BIGSUDS"
.IX Header "BIGSUDS"
.SS "Requirement of bigsuds"
.IX Subsection "Requirement of bigsuds"
This tool depends on bigsuds. Please install this library from F5 dev central
manually. Otherwise this script will not work.
.PP
You can download bigsuds from here:
.PP
https://devcentral.f5.com/d/bigsuds\-python\-icontrol\-library <https://devcentral.f5.com/d/bigsuds-python-icontrol-library>
.PP
Unzip it and run
.PP
.Vb 1
\&  sudo python setup.py install
.Ve
.PP
You may also install bigsuds from the contrib dir of the fapi source tree.
.SS "iControl reference"
.IX Subsection "iControl reference"
Through bigsuds you can do everything what iControl can do:
.PP
<https://devcentral.f5.com/wiki/icontrol.apireference.ashx>
.SH "QUICK START"
.IX Header "QUICK START"
Update your sources list:
.PP
.Vb 4
\&  curl http://deb.buetow.org/apt/pubkey.gpg | sudo apt\-key add \-
\&  echo deb http://deb.buetow.org/apt wheezy main |
\&    sudo tee /etc/apt/sourcees.list.d/buetoworg.list
\&  sudo aptitude update
.Ve
.PP
And run
.PP
.Vb 3
\&  sudo aptitude install fapi
\&  cp /usr/share/fapi/fapi.conf.sample ~/.fapi.conf
\&  vim ~/.fapi.conf
.Ve
.PP
Or if you want to install it from the source dir, just run:
.PP
.Vb 2
\&  make
\&  sudo make install
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Listing"
.IX Subsection "Listing"
If you want to list all configured objects on your partition just run
.PP
.Vb 3
\&  fapi node # To list all nodes
\&  fapi pool # To list all pool
\&  ... # etc
.Ve
.SS "Setting up a simple pool"
.IX Subsection "Setting up a simple pool"
.Vb 4
\&  # Creating two nodes, fapi auto resolves the IP addresses, and use the
\&  # FQDN as the node name. 
\&  fapi node fooserver1.example.com create
\&  fapi node fooserver2.example.com create
\&
\&  # Creating a pool and add the nodes to it. Also specify the node ports to 
\&  # use by the monitors (and maybe PAT if enabled)
\&  fapi pool foopool create
\&  fapi pool foopool add member fooserver1.example.com:80
\&  fapi pool foopool add member fooserver2.example.com:80
\&
\&  # Add a monitor to the pool
\&  fapi pool foopool add monitor http_lbtest
.Ve
.SS "Setting up a simple nPath Service"
.IX Subsection "Setting up a simple nPath Service"
A simple nPath service can be created as follows.
.PP
.Vb 2
\&  fapi vserver myvserver.example.com:80 create PROTOCOL_TCP nPath
\&  fapi vserver myvserver.example.com:80 set pool foopool
\&
\&  # Restrict the vservers to a specific VLAN (IMPORTANT! security
\&  # hole otherwise!)
\&  fapi vserver myvserver.example.com:80 set vlan VLANNAME
\&  fapi vserver myvserver.example.com:443 set vlan VLANNAME
\&
\&  # Put the VirtualAddress of the vserver into a specific traffic group
\&  fapi vip myserver.example.com set tgroup some\-traffic\-group
.Ve
.PP
And everything can be deleted as folows:
.PP
.Vb 2
\&  # You can also specify the full object name (including the partition)
\&  fapi vserver /Common/myvserver.example.com_80 delete
\&
\&  # Or just the way the service was created from command line
\&  fapi vserver myvserver.example.com:443 delete
\&
\&  fapi pool foopool delete
\&  fapi node fooserver1.example.com delete
\&  fapi node fooserver2.example.com delete
.Ve
.SS "Setting up simple \s-1HTTP\s0 \s-1NAT\s0 Services"
.IX Subsection "Setting up simple HTTP NAT Services"
A simple \s-1HTTP\s0 NATed service can be created as follows.
.PP
.Vb 3
\&  fapi vserver myvserver.example.com:80 create PROTOCOL_TCP http
\&  fapi vserver myvserver.example.com:80 set vlan VLANNAME
\&  fapi vserver myvserver.example.com:80 set pool foopool
.Ve
.PP
In order to make this work your application servers need to have setup a
default route to the loadbalancers floating self \s-1IP\s0.
.SS "Setting up simple \s-1SNAT\s0 Services"
.IX Subsection "Setting up simple SNAT Services"
Same as setting up a NATed services, but you don't need to configure default 
routes from your application servers to the loadbalancers floating self \s-1IP\s0.
.PP
You need also to set the \s-1SNAT\s0 flag as follows:
.PP
.Vb 1
\&  fapi vserver myvserver.example.com:80 set snat automap
.Ve
.SS "Settung up simple \s-1SNAT\s0 Services with \s-1SSL\s0 offloading enabled"
.IX Subsection "Settung up simple SNAT Services with SSL offloading enabled"
Just like \s-1SNAT\s0 service (use port 443) but with these additional steps
.PP
First Upload the \s-1SSL\s0 certificate to the F5 \s-1BIG\s0 \s-1IP\s0 (e.g. System \-> File Management
\&\-> \s-1SSL\s0 Certificate List on \s-1BIG\s0 \s-1IP\s0 V11.4).
.PP
.Vb 3
\&  # Afterwards create a new SSL profile to use the new certificate:
\&  # (Will automatically use key/crt myserver.example.com.{key,crt})
\&  fapi profileclientssl myserver.example.com create
\&
\&  # Then attach that profile to the vserver (default context is 
\&  # PROFILE_TYPE_CLIENT_SSL, which means SSL between F5 and Clients)
\&  fapi vserver myvserver.example.com:443 profile add myserver.example.com
.Ve
.SS "About the \s-1NAME\s0 argument"
.IX Subsection "About the NAME argument"
In most cases \s-1NAME\s0 can be a hostname, \s-1FQDN\s0 or an \s-1IP\s0 address. Optionally folled
by a port:
.PP
.Vb 1
\&  NAME := fqdn|hostname|ip[:ip2[:port]]
.Ve
.PP
Examples:
.PP
.Vb 3
\&  # Auto resolving of the virtual address (IP) and auto port 80. The vserver
\&  # name will have added an automatic _PORT suffix to it\*(Aqs name.
\&  fapi vserver fqdn.example.com create
\&
\&  # Or just ignore the auto port, will not add any _PORT suffix to the 
\&  # vserver name.
\&  fapi \-a ....
\&
\&  # Example:
\&  fapi \-a vserver fqdn.example.com_ssl create
\&
\&  # Auto resolving of the virtual address (IP)
\&  fapi vserver fqdn.example.com:443 create
\&
\&  # Auto resolving of the FQDN (vserver name) and the virtual address (IP) 
\&  # and auto port 80
\&  fapi vserver hostname create
\&
\&  # Auto resolving of the FQDN (vserver name) and the virtual address (IP) 
\&  fapi vserver hostname:443 create
\&
\&  # vserver name and its virtual address will be 1.2.3.4 and auto port 80
\&  fapi vserver 1.2.3.4 create
\&
\&  # vserver name and its virtual address will be 1.2.3.4 
\&  fapi vserver 1.2.3.4:443 create
\&
\&  # vserver name is foo, its virtual address 1.2.3.4 and port is 80
\&  fapi vserver foo:1.2.3.4:80 create
\&
\&  # vserver name is 1.2.3.5, its virtual address 1.2.3.4 and port is 80
\&  fapi vserver 1.2.3.5:1.2.3.4:80 create
.Ve
.PP
Similar may apply to other object types such as nodes and vips.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul C. Buetow \- <paul@buetow.org>
.PP
Also see <http://fapi.buetow.org>