<commit_before>#netscaler

####Table of Contents

1. [Overview](#overview)
2. [Module Description - What the module does and why it is useful](#module-description)
3. [Setup - The basics of getting started with netscaler](#setup)
    * [Setup requirements](#setup-requirements)
    * [Beginning with netscaler](#beginning-with-netscaler)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
5. [Limitations - OS compatibility, etc.](#limitations)
6. [Development - Guide for contributing to the module](#development)

##Overview

The netscaler module enables Puppet configuration of Citrix NetScaler devices through types and REST-based providers.

##Module Description

This module uses REST to manage various aspects of NetScaler load balancers, and acts
as a foundation for building higher level abstractions within Puppet.

The module allows you to manage NetScaler nodes and pool configuration through Puppet.

##Setup

###Beginning with netscaler

Before you can use the netscaler module, you must create a proxy system able to run `puppet device`.  In order to do so, you will have a Puppet master and a Puppet agent as usual, and the agent will be the "proxy system" for the `puppet device` subcommand.

**NOTE: `puppet device` was designed to interact with admininistrative interfaces in order to run commands that implement types and providers. `puppet device` allows you to write a resource to talk to the device and translates the module into network calls.**

**TODO^^^ Run that by Hunter.**

This means you must create a device.conf file in the Puppet conf directory (either /etc/puppet or /etc/puppetlabs/puppet) on the Puppet agent. Within your device.conf, you must have:

**TODO:Check this**
~~~
[bigip]
type netscaler
url https://<USERNAME>:<PASSWORD>@<IP ADDRESS OF BIGIP>/
~~~

In the above example, <USERNAME> and <PASSWORD> refer to Puppet's login for the device.

Additionally, you must install the faraday gem on the proxy host (Puppet agent). You can do this by declaring the **TODO:What class?** class on that host. If you do not install the faraday gem, the module will not work.

##Usage

###Set up two load-balanced web servers.

####Before you begin

This example is built around the following infrastructure: A server running a Puppet master is connected to the NetScaler device. The NetScaler device contains a management VLAN, a client VLAN which will contain the virtual server, and a server VLAN which will connect to the two web servers the module will be setting up. 

In order to successfully set up your web servers, you must know the following information about your systems:

1. The IP addresses of both of the web servers;
2. The names of the nodes each web server will be on;
3. The ports the web servers are listening on; and
4. The IP address of the virtual server.

####Step One: Classifying your servers

In your site.pp file, enter the below code:

**TODO:Update for NetScaler**
~~~
node bigip {
f5_node { '/Common/WWW_Server_1':
  ensure                   => 'present',
  address                  => '172.16.226.10',
  description              => 'WWW Server 1',
  availability_requirement => 'all',
  health_monitors          => ['/Common/icmp'],
}->
f5_node { '/Common/WWW_Server_2':
  ensure                   => 'present',
  address                  => '172.16.226.11',
  description              => 'WWW Server 2',
  availability_requirement => 'all',
  health_monitors          => ['/Common/icmp'],
}->
f5_pool { '/Common/puppet_pool':
  ensure                    => 'present',
  members                   => [{ name => '/Common/WWW_Server_1', port => '80'}, { name => '/Common/WWW_Server_1', port => '80'}],
  availability_requirement  => 'all',
  health_monitors           => ['/Common/http_head_f5'],
}->
f5_virtualserver { '/Common/puppet_vs':
  ensure                    => 'present',
  provider                  => 'standard',
  default_pool              => '/Common/puppet_pool',
  destination_address       => '192.168.80.100',
  destination_mask          => '255.255.255.255',
  http_profile              => '/Common/http',
  service_port              => '80',
  protocol                  => 'tcp',
  source                    => '0.0.0.0/0',
  vlan_and_tunnel_traffic   => {'enabled' => ['/Common/Client']},
}
}
~~~

**The order of your resources is extremely important.** You must first establish your two web servers. In the code above, they are **TODO:Update this**`f5_node { '/Common/WWW_Server_1'...` and `f5_node { '/Common/WWW_Server_2'...`. Each have the minimum number of parameters possible, and are set up with a health monitor that will ping each server directly to make sure it is still responsive. 

Then you establish the pool of servers. The pool is also set up with the minimum number of parameters. The health monitor for the pool will run an https request to see that a webpage is returned.

The virtual server brings your setup together. Your virtual server **must** have a `provider` assigned. 

####Step Two: Run your Puppet master

Run the following to have the Puppet master apply your classifications and configure the NetScaler device: 

~~~
$ FACTER_url=https:/<USERNAME>:<PASSWORD>@<IP ADDRESS OF BIGIP> puppet device -v
~~~

If you do not run this command, clients will not be able to make requests to the web servers.

At this point, your basic web servers should be up and fielding requests.

###Tips and Tricks

####Basic Usage**TODO**

Once you've established a basic configuration, you can explore the providers and their allowed options by running `puppet resource <TYPENAME>` for each type. This will provide a starting point for seeing what's already on your NetScaler. If anything failed to set up properly, it will not show up when you run the command.

To begin with you can simply call the types from the proxy system.

**TODO:Update**
```
$ FACTER_url=https://admin:admin@f5.hostname/ puppet resource f5_node
```

You can change a property by hand this way, too.

**TODO:Update**
```
$ FACTER_url=https://admin:admin@f5.hostname/ puppet resource f5_user node ensure=absent
``` 

####Role and Profiles
The [above example](#set-up-two-loadbalanced-web-servers) is for setting up a simple configuration of two web servers. However, for anything more complicated, you will want to use the roles and profiles pattern when classifying nodes or devices for NetScaler.

####Custom HTTP monitors
If you have a '/Common/http_monitor (which is available by default), then when you are creating a /Common/custom_http_monitor you can simply use `parent_monitor => '/Common/http'` so that you don't have to duplicate all values.

##Reference

###Public Types

* [`netscaler_lbmonitor`](#type-netscaler_monitor)
* [`netscaler_server`](#type-netscaler_server)
* [`netscaler_service`](#type-netscaler_service)
* [`netscaler_service_lbmonitor-bind`](#type-netscaler_service_lbmonitor-bind)

###Type: netscaler_lbmonitor
 
Manages loadbalancer monitoring on the NetScaler appliance.  If the service is domain-based, you must use the `add server` command to create the 'server' entry before you create the service. Then, specify the `server` parameter in the `add server` command.
 
####Parameters

All parameters, except where otherwise noted, are optional. Their default values are determined by your particular NetScaler setup.

#####`account_application_ids`
Specifies a list of Acct-Application-Id attribute value pairs (AVPs) for the Capabilities-Exchange-Request (CER) message to use for monitoring Diameter servers. A maximum of eight of AVPs are supported in a monitoring message.
 
Valid options: An AVP or an array of up to 8 AVPs<commit_msg>Fixup some example artifacts in NetScaler readme<commit_after>#netscaler

####Table of Contents

1. [Overview](#overview)
2. [Module Description - What the module does and why it is useful](#module-description)
3. [Setup - The basics of getting started with netscaler](#setup)
    * [Setup requirements](#setup-requirements)
    * [Beginning with netscaler](#beginning-with-netscaler)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
5. [Limitations - OS compatibility, etc.](#limitations)
6. [Development - Guide for contributing to the module](#development)

##Overview

The netscaler module enables Puppet configuration of Citrix NetScaler devices through types and REST-based providers.

##Module Description

This module uses REST to manage various aspects of NetScaler load balancers, and acts
as a foundation for building higher level abstractions within Puppet.

The module allows you to manage NetScaler nodes and pool configuration through Puppet.

##Setup

###Beginning with netscaler

Before you can use the netscaler module, you must create a proxy system able to run `puppet device`.  In order to do so, you will have a Puppet master and a Puppet agent as usual, and the agent will be the "proxy system" for the `puppet device` subcommand.

**NOTE: `puppet device` was designed to interact with admininistrative interfaces in order to run commands that implement types and providers. `puppet device` allows you to write a resource to talk to the device and translates the module into network calls.**

**TODO^^^ Run that by Hunter.**

This means you must create a device.conf file in the Puppet conf directory (either /etc/puppet or /etc/puppetlabs/puppet) on the Puppet agent. Within your device.conf, you must have:

**TODO:Check this**
~~~
[certname]
type netscaler
url https://<USERNAME>:<PASSWORD>@<netscaler1.example.com>/
~~~

In the above example, <USERNAME> and <PASSWORD> refer to Puppet's login for the device.

Additionally, you must install the faraday gem on the proxy host (Puppet agent). You can do this by declaring the **TODO:What class?** class on that host. If you do not install the faraday gem, the module will not work.

##Usage

###Set up two load-balanced web servers.

####Before you begin

This example is built around the following infrastructure: A server running a Puppet master is connected to the NetScaler device. The NetScaler device contains a management VLAN, a client VLAN which will contain the virtual server, and a server VLAN which will connect to the two web servers the module will be setting up. 

In order to successfully set up your web servers, you must know the following information about your systems:

1. The IP addresses of both of the web servers;
2. The names of the nodes each web server will be on;
3. The ports the web servers are listening on; and
4. The IP address of the virtual server.

####Step One: Classifying your servers

In your site.pp file, enter the below code:

**TODO:Update**

~~~
node 'certname' {
netscaler_server { '1_10_server1':
  ensure  => present,
  address => '192.168.3.11',
  }
netscaler_service { '1_10_service1':
  ensure      => 'present',
  server_name => '1_10_server1',
  port        => '80',
  protocol    => 'HTTP',
  comments    => 'This is a comment'
}
netscaler_lbvserver { '1_10_lbvserver1':
  ensure       => 'present',
  service_type => 'HTTP',
  ip_address   => '192.168.3.11',
  port         => '8080',
  state        => true,
}
netscaler_lbvserver_service_binding { '1_10_lbvserver1/1_10_service1':
  ensure => 'present',
  weight => '100',
}
netscaler_rewritepolicy { '2_4_rewritepolicy_test1':
  ensure                  => 'present',
  action                  => 'NOREWRITE',
  comments                => 'comment',
  expression              => 'HTTP.REQ.URL.SUFFIX.EQ("")',
  undefined_result_action => 'DROP',
}
netscaler_csvserver { '2_4_csvserver_test1':
  ensure        => 'present',
  service_type  => 'HTTP',
  state         => true,
  ip_address    => '172.16.17.32',
  port          => '8080',
}
netscaler_csvserver_rewritepolicy_binding { '2_4_csvserver_test1/2_4_rewritepolicy_test1':
  ensure               => present,
  priority             => 1,
  invoke_vserver_label => '2_4_csvserver_test1',
  choose_type          => 'Request',
}
}
~~~


####Step Two: Run your Puppet master

Run the following to have the Puppet master apply your classifications and configure the NetScaler device: 

~~~
$ FACTER_url=https://<USERNAME>:<PASSWORD>@<NETSCALER1.EXAMPLE.COM> puppet device -v
~~~

If you do not run this command, clients will not be able to make requests to the web servers.

At this point, your basic web servers should be up and fielding requests.

###Tips and Tricks

####Basic Usage**TODO**

Once you've established a basic configuration, you can explore the providers and their allowed options by running `puppet resource <TYPENAME>` for each type. This will provide a starting point for seeing what's already on your NetScaler. If anything failed to set up properly, it will not show up when you run the command.

To begin with you can simply call the types from the proxy system.

**TODO:Update**
```
$ FACTER_url=https://admin:admin@netscaler1.example.com/ puppet resource netscaler_lbvserver
```

####Role and Profiles
The [above example](#set-up-two-loadbalanced-web-servers) is for setting up a simple configuration of two web servers. However, for anything more complicated, you will want to use the roles and profiles pattern when classifying nodes or devices for NetScaler.

####Custom HTTP monitors
If you have a '/Common/http_monitor (which is available by default), then when you are creating a /Common/custom_http_monitor you can simply use `parent_monitor => '/Common/http'` so that you don't have to duplicate all values.

##Reference

###Public Types

* [`netscaler_lbmonitor`](#type-netscaler_monitor)
* [`netscaler_server`](#type-netscaler_server)
* [`netscaler_service`](#type-netscaler_service)
* [`netscaler_service_lbmonitor-bind`](#type-netscaler_service_lbmonitor-bind)

###Type: netscaler_lbmonitor
 
Manages loadbalancer monitoring on the NetScaler appliance.  If the service is domain-based, you must use the `add server` command to create the 'server' entry before you create the service. Then, specify the `server` parameter in the `add server` command.
 
####Parameters

All parameters, except where otherwise noted, are optional. Their default values are determined by your particular NetScaler setup.

#####`account_application_ids`
Specifies a list of Acct-Application-Id attribute value pairs (AVPs) for the Capabilities-Exchange-Request (CER) message to use for monitoring Diameter servers. A maximum of eight of AVPs are supported in a monitoring message.
 
Valid options: An AVP or an array of up to 8 AVPs
{'fraction_non_alphanumeric': 0.09077868852459016, 'fraction_numerical': 0.012295081967213115, 'mean_word_length': 4.0157588215142175, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 83, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 11, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1577122', 'n_tokens_mistral': 4267, 'n_tokens_neox': 4057, 'n_words': 1804}