#f5
####Table of Contents
- Overview
- Module Description - What the module does and why it is useful
- [Setup - The basics of getting started with f5(#setup)
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
##Overview
The F5 module allows you to centralize the management of your F5 devices (running 11.0+) via many different types and providers. This module, and the current design of it, is to be deprecated shortly with the introduction of a new REST based module written from scratch. We have recently overhauled this module to work with Puppet 3+ and modern versions of Ruby, but the new module will be substantially different.
As a result of the new planned development this module has been only lightly tested and we welcome bug reports on any issues you find with it.
##Module Description
This module uses SOAP to manage F5 devices running 11.0+. It consists of nineteen resources covering everything from users to irules.
##Setup
###What f5 affects
- F5 device configuration.
- Puppet device configuration.
###Setup Requirements
As F5 devices cannot run Puppet natively we require the use of a proxy system. This system must be running Puppet and have the "Savon"(http://www.savonrb.com) Ruby gem installed on it for working with the SOAP api.
The following profile class would deploy an appropriate configuration as well as setup a cron job to run the F5 configuration once an hour.
class profile::f5_proxy(
$hostname = 'f5.puppetlabs.lan',
$username = 'admin',
$password = 'admin'
) {
include f5
f5::config { $hostname:
username => $username,
password => $password,
url => $hostname,
target => "${::settings::confdir}/device/${hostname}"
}
cron { "bigip-puppet-device-run":
command => "puppet device --deviceconfig ${::settings::confdir}/device/${hostname}",
minute => fqdn_rand(60),
}
}Once you've run this on a proxy you can then create a class and apply it to a node with the name of the f5 (in the above example f5.puppetlabs.lan).
class profile:f5_users {
f5_user { 'test':
ensure => present,
password => {'is_encrypted' => 'false', 'password' => 'test'}
}
}###Beginning with [Modulename]
To begin with you can simply call the types from the proxy system we set up earlier. You can run puppet resource directly.
$ FACTER_url=https://admin:[email protected]/ puppet resource f5_user
You can change a property by hand this way too.
$ FACTER_url=https://admin:[email protected]/ puppet resource f5_user test ensure=absent
##Usage
You can explore the providers and the options they allow by running puppet resource f5_x for each provider to see what's already on your F5 as a starting point. Beyond that all the parameters available for each resource can be found below.
##Reference
###Global
All resource names are required to be in the format of /Partition/name.
###f5_certificate
f5_certificate can be used to manage SSL certificates on the F5.
####name
The name of the certificate to manage.
####content
The certificate content in PEM format. (sha1 fingerprint).
####real_content
The actual certificate content in PEM format.
####mode
The management mode of the certificate.
Valid options are: MANAGEMENT_MODE_DEFAULT, MANAGEMENT_MODE_WEBSERVER, MANAGEMENT_MODE_EM, MANAGEMENT_MODE_IQUERY, MANAGEMENT_MODE_IQUERY_BIG3D
###f5_external_class
f5_external_class manages external classes (datagroups).
####name
The name of the external class to manage.
####file_format
The file format for the specified classes.
Valid options are: FILE_FORMAT_UNKNOWN, FILE_FORMAT_CSV
####file_mode
The file modes for the specified classes.
Valid options are: FILE_MODE_UNKNOWN, FILE_MODE_TYPE_READ, FILE_MODE_TYPE_READ_WRITE
####file_name
The file names for the specified classes.
####data_separator
The data seperator for the specified classes.
####type
The class types for the specified classes.
Valid options are: CLASS_TYPE_UNDEFINED, CLASS_TYPE_ADDRESS, CLASS_TYPE_STRING, CLASS_TYPE_VALUE
###f5_file
f5_file manages arbitary files on the f5.
####path
The absolute filepath to a file on the F5.
####content
The contents of the file.
###f5_inet
f5_inet manages the inet properties on the F5.
#####name
The BigIP hostname.
#####hostname
The BigIP hostname.
#####ntp_server_address
The NTP server address.
###f5_key
f5_key manages security keys on the F5.
####name
The name of the key to manage.
####content
The certificate key in PEM format (sha1 fingerprint).
####real_content
Stores actual key PEM-formatted content.
####mode
The key management mode.
Valid options are: MANAGEMENT_MODE_DEFAULT, MANAGEMENT_MODE_WEBSERVER, MANAGEMENT_MODE_EM, MANAGEMENT_MODE_IQUERY, MANAGEMENT_MODE_IQUERY_BIG3D
###f5_monitor
####name
The name of the monitor to manage.
####is_directly_usable
Determines if the specified monitor templates can be used directly, or if a user-defined monitor based on each monitor must be created first before it can be used.
Valid options are: true (default), false
####is_read_only
Determines if the specified monitor templates are read-only. The user can only modify properties for read/write monitor templates.
Valid options are: true, false (default)
####manual_resume_state
The monitor templates' manual resume states. When enabled and a monitor has marked an object down, that object will not be marked up by the monitor, i.e. the object will be manually marked up.
Valid options are: STATE_DISABLED, STATE_ENABLED
####parent_template
The parent monitor templates from which the specified monitor templates are derived. A user-defined monitor template will get its defaults from its parent monitor template.
Default: ''
####template_destination
The destination IP:port values for the specified templates. NOTE: This should only be done when the monitor templates in 'template_names' have NOT been associated to any node addresses or pool members.
Default: ['ATYPE_STAR_ADDRESS_STAR_PORT', ':']
####template_integer_property
The integer property values of the specified monitor templates.
Default: { 'ITYPE_INTERVAL' => 5, 'ITYPE_TIMEOUT' => 16 }
####template_state
The monitor templates' enabled/disabled states. This will enable/disable all instances that use the specified templates. This serves as a quick and convenient method to enable/disable all instances, but if you want only to enable/disable a specific instance, use set_instance_enabled.
Valid options: STATE_DISABLED, STATE_ENABLED
####template_string_property
The string property values of the specified monitor templates.
####template_type
The template types of the specified monitor templates.
Valid options: TTYPE_UNSET, TTYPE_ICMP, TTYPE_TCP, TTYPE_TCP_ECHO, TTYPE_EXTERNAL, TTYPE_HTTP, TTYPE_HTTPS, TTYPE_NNTP, TTYPE_FTP, TTYPE_POP3, TTYPE_SMTP, TTYPE_MSSQL, TTYPE_GATEWAY, TTYPE_IMAP, TTYPE_RADIUS, TTYPE_LDAP, TTYPE_WMI, TTYPE_SNMP_DCA_BASE, TTYPE_SNMP_DCA, TTYPE_REAL_SERVER, TTYPE_UDP, TTYPE_NONE, TTYPE_ORACLE, TTYPE_SOAP, TTYPE_GATEWAY_ICMP, TTYPE_SIP, TTYPE_TCP_HALF_OPEN, TTYPE_SCRIPTED, TTYPE_WAP, TTYPE_RPC, TTYPE_SMB, TTYPE_SASP, TTYPE_MODULE_SCORE, TTYPE_FIREPASS, TTYPE_INBAND, TTYPE_RADIUS_ACCOUNTING, TTYPE_DIAMETER, TTYPE_VIRTUAL_LOCATION, TTYPE_MYSQL, TTYPE_POSTGRESQL
####template_transparent_mode
The monitor template transparent mode.
Valid options: true, false
###f5_node
Manage F5 nodes.
####name
The nodes hostname.
####connection_limit
The connection limits for the specified node addresses.
####dynamic_ratio
The dynamic ratios of a node addresses.
####addresses
The IP addresses of the specified node addresses.
####ratios
The ratios for the specified node addresses.
####session_enabled_state
The states that allows new sessions to be established for the specified node addresses.
Valid options: STATE_DISABLED, STATE_ENABLED
###f5_pool
Manage F5 pools.
####name
The name of the pool to manage.
####action_on_service_down
The action to take when the node goes down for the specified pools.
Valid options: SERVICE_DOWN_ACTION_NONE, SERVICE_DOWN_ACTION_RESET, SERVICE_DOWN_ACTION_DROP, SERVICE_DOWN_ACTION_RESELECT
####allow_nat_state
The states indicating whether NATs are allowed for the specified pool.
Valid options: STATE_DISABLED, STATE_ENABLED
####allow_snat_state
The states indicating whether SNATs are allowed for the specified pools.
Valid options: STATE_DISABLED, STATE_ENABLED
####client_ip_tos
The IP ToS values for client traffic for the specified pools.
####client_link_qos
The link QoS values for client traffic for the specified pools.
####gateway_failsafe_device
The gateway failsafe devices for the specified pools.
####lb_method
The load balancing methods for the specified pools.
Valid options: LB_METHOD_ROUND_ROBIN, LB_METHOD_RATIO_MEMBER, LB_METHOD_LEAST_CONNECTION_MEMBER, LB_METHOD_OBSERVED_MEMBER, LB_METHOD_PREDICTIVE_MEMBER, LB_METHOD_RATIO_NODE_ADDRESS, LB_METHOD_LEAST_CONNECTION_NODE_ADDRESS, LB_METHOD_FASTEST_NODE_ADDRESS, LB_METHOD_OBSERVED_NODE_ADDRESS, LB_METHOD_PREDICTIVE_NODE_ADDESS, LB_METHOD_DYNAMIC_RATIO, LB_METHOD_FASTEST_APP_RESPONSE, LB_METHOD_LEAST_SESSIONS, LB_METHOD_DYNAMIC_RATIO_MEMBER, LB_METHOD_L3_ADDR, LB_METHOD_UNKNOWN, LB_METHOD_WEIGHTED_LEAST_CONNECTION_MEMBER, LB_METHOD_WEIGHTED_LEAST_CONNECTION_NODE_ADDRESS, LB_METHOD_RATIO_SESSION, LB_METHOD_RATIO_LEAST_CONNECTION_MEMBER, LB_METHOD_RATIO_LEAST_CONNECTION_NODE_ADDRESS
####member
The list of pool members.
####minimum_active_member
The minimum active member counts for the specified pools.
####minimum_up_member
The minimum member counts that are required to be in the up state for the specified pools.
####minimum_up_member_action
The actions to be taken if the minimum number of members required to be UP for the specified pools is not met.
####minimum_up_member_enabled_state
The states indicating that the feature that requires a minimum number of members to be UP is enabled/disabled for the specified pools.
####monitor_association
The monitor associations for the specified pools, i.e. the monitor rules used by the pools. The pool monitor association should be specified as a hash consisting of the following keys:
{ 'monitor_templates' => [],
'quorum' => '0',
'type' => 'MONITOR_RULE_TYPE_AND_LIST' }
####server_ip_tos
The IP ToS values for server traffic for the specified pools.
####server_link_qos
The link QoS values for server traffic for the specified pools.
####simple_timeout
The simple timeouts for the specified pools.
####slow_ramp_time
The ramp-up time (in seconds) to gradually ramp up the load on newly added or freshly detected UP pool members.
###f5_profileclientssl
Manage F5 Client SSL profiles.
####name
The name of the client SSL profile to manage.
####certificate_file
The certificate filenames to be used by BIG-IP acting as an SSL server.
####key_file
The key filenames to be used by BIG-IP acting as an SSL server. If a full path is not specified, the file name is relative to /config/ssl/ssl.key."
####ca_file
The CA to use to validate client certificates.
####client_certificate_ca_file
The CA to use to validate client certificates.
####peer_certification_mode
The peer certification modes for the specified client SSL profiles.
####chain_file
The certificate chain filenames for the specified client SSL profiles.
###f5_profilepersistence
Manage the loadbalancer's persistence profile.
####name
The persistence profile name.
####across_pool_state
The states to indicate whether persistence entries added under this profile are available across pools.
####across_service_state
The states to indicate whether persistence entries added under this profile are available across services.
####across_virtual_state
The states to indicate whether persistence entries added under this profile are available across virtuals.
####cookie_expiration
The cookie expiration in seconds for the specified Persistence profiles. Applicable when peristence mode is PERSISTENCE_MODE_COOKIE.
####cookie_hash_length
The cookie hash lengths for the specified profiles. Applicable when peristence mode is PERSISTENCE_MODE_COOKIE, and cookie persistence method is COOKIE_PERSISTENCE_METHOD_HASH.
####cookie_hash_offset
The cookie hash offsets for the specified profiles. Applicable when peristence mode is PERSISTENCE_MODE_COOKIE, and cookie persistence method is COOKIE_PERSISTENCE_METHOD_HASH
####cookie_name
The cookie names for the specified Persistence profiles. Applicable when peristence mode is PERSISTENCE_MODE_COOKIE.
####cookie_persistence_method
The cookie persistence methods to be used when in cookie persistence mode. Applicable when peristence mode is PERSISTENCE_MODE_COOKIE.
####default_profile
The names of the default profiles from which the specified profiles will derive default values for its attributes.
####description
The descriptions for a set of persistence profiles.
####ending_hash_pattern
The pattern marking the end of the section of payload data whose hashed value is used for the persistence value for a set of persistence profiles. This only returns useful values if the persistence mode is PERSISTENCE_MODE_HASH and the hash method is PERSISTENCE_HASH_CARP.
####hash_length
The length of payload data whose hashed value is used for the persistence value for a set of persistence profiles. This only returns useful values if the persistence mode is PERSISTENCE_MODE_HASH and the hash method is PERSISTENCE_HASH_CARP.
####hash_method
The hash method used to generate the persistence values for a set of persistence profiles. This only returns useful values if the persistence mode is PERSISTENCE_MODE_HASH.
####hash_more_data_state
The enabled state whether to perform another hash operation after the current hash operation completes for a set of persistence profiles. This only returns useful values if the persistence mode is PERSISTENCE_MODE_HASH and the hash method is PERSISTENCE_HASH_CARP.
####hash_offset
The offset to the start of the payload data whose hashed value is used as the persistence value for a set of persistence profiles. This only returns useful values if the persistence mode is PERSISTENCE_MODE_HASH and the hash method is PERSISTENCE_HASH_CARP.
####map_proxy_address
The proxy map address used when map proxies state is enabled on source address persistence mode.
####map_proxy_class
The proxy map IP address class/datagroup name used when map known proxies state is enabled on source address persistence mode.
####map_proxy_state
The states to indicate whether to map known proxies when the persistence mode is source address affinity.
####mask
The masks used in either simple or sticky persistence mode.
####maximum_hash_buffer_size
The maximum size of the buffer used to hold the section of the payload data whose hashed value is used for the persistence value for a set of persistence values. This only returns useful values if the persistence mode is PERSISTENCE_MODE_HASH and the hash method is PERSISTENCE_HASH_CARP.
####mirror_state
The mirror states for the specified Persistence profiles.
####msrdp_without_session_directory_state
The states to indicate whether MS terminal services have been configured without a session directory for the specified Persistence profiles.
####override_connection_limit_state
The state indicating, when enabled, that the pool member connection limits are not enforced for persisted clients.
####persistence_mode
The persistence modes for the specified Persistence profiles.
####rule
The UIE rules for the specified Persistence profiles. Applicable when peristence mode is PERSISTENCE_MODE_UIE.
####sip_info
The sip_info headers for the specified Persistence profiles. Applicable when peristence mode is PERSISTENCE_MODE_SIP.
####starting_hash_pattern
The pattern marking the start of the section of payload data whose hashed value is used for the persistence value for a set of persistence profiles. This only returns useful values if the persistence mode is PERSISTENCE_MODE_HASH and the hash method is PERSISTENCE_HASH_CARP.
####timeout
The timeout for the specified Persistence profiles. The number of seconds to timeout a persistence entry.
###f5_route
Manage static routes within the F5.
####name
The name of the routing object to manage.
####description
Description of the route.
####destination
Destination of the route
####netmask
Netmask of the route.
####mtu
MTU of the route
####gateway
Gateway of the route
####pool
Pool to route to.
####vlan
VLAN to route to.
###f5_rule
####name
The name of the rule to manage.
####definition
The rule definition.
###f5_snat
#####name
The name of the snat to manage.
#####connection_mirror_state
The connection mirror states for a specified SNATs.
Valid options are: STATE_DISABLED, STATE_ENABLED
#####original_address
The list of original client addresses used to filter the traffic to the SNATs."
#####source_port_behavior
The source port behavior for the specified SNATs.
Valid options are: SOURCE_PORT_PRESERVE, SOURCE_PORT_PRESERVE_STRICT, SOURCE_PORT_CHANGE
#####translation_target
The translation targets for the specified SNATs. If the target type is SNAT_TYPE_AUTOMAP, then the translation object should be empty.
#####vlan
The list of VLANs on which access to the specified SNATs is disabled/enabled.
###f5_snatpool
####name
The name of the snatpool to manage.
####membership
Membes of the snat pool.
####member
The list of members belonging to the specified SNAT pools.
###f5_snattranslationaddress
####name
The snat translation address to manage.
####addresses
The IP addresses of the specified SNAT translation address/
####arp_state
The ARP states for the specified translation SNAT address.
Valid options are: STATE_DISABLED, STATE_ENABLED
####connection_limit
The connection limits of the specified original SNAT translation address.
####enabled_state
The state of a SNAT translation address.
Valid options are: STATE_DISABLED, STATE_ENABLED
####ip_timeout
The IP idle timeouts of the specified SNAT translation address.
####tcp_timeout
The TCP idle timeouts of the specified SNAT translation address.
####udp_timeout
The UDP idle timeouts of the specified SNAT translation addresses.
###f5_snmpconfiguration
WARNING: The backend API for snmpconfiguration is extremely brittle and any mistaken input can easily crash the SOAP handler.
####name
The name to show via SNMP.
####access_info
Creates access maps from group/securitymodel/security level to a view.
####agent_group_id
Sets the agent group id.
####agent_interface
Sets the interface information for the agent
####agent_listen_address
Sets a list of agent listen addresses. This makes the agent listen on the specified list of sockets instead of the default port, which is 161.
####agent_trap_state
Sets the authentication trap enabled state.
####agent_user_id
The agent user id.
####auth_trap_state
The auth trap state.
####check_disk
Create a disk check instance.
####check_file
Create a file check instance.
####check_load
Create a load check instance.
####check_process
Create a process check instance.
####client_access
Creates a list of client access controls. These are stored in the /etc/hosts.allow file.
####community_to_security_info
Creates mappings from a source/community pair to security names. The first source/community combination that matches the incoming packet is selected.
####create_user
Creates SNMPV3 users.
####engine_id
Sets the snmp engine identifier.
####exec
Creates a program instance.
####exec_fix
Sets an exec fix instance that registers a command that knows how to fix errors with the given program.
####generic_traps_v2
Creates generic traps that allows any type of trap destination to be specified with any version of SNMP.
####group_info
Creates mappings from securitymodel/securityname to group.
####ignore_disk
Adds disk devices to the ignore list.
####pass_through
Creates a list of pass through controls.
####pass_through_persist
Creates a list of persist pass through controls.
####process_fix
Sets a process fix instance that registers a command that knows how to fix errors with the given process.
####proxy
Creates a list of snmp proxies.
####readonly_community
Creates read-only communities that can be used to access the agent.
####readonly_user
Creates SNMPv3 USM read-only users in the VACM access configuration tables.
####readwrite_community
Creates read-write communities that can be used to access the agent.
####readwrite_user
Creates SNMPv3 USM read-write users in the VACM access configuration tables.
####system_information
Sets the system location, system contact, and system name for the agent.
####trap_community
Sets the trap community string.
####view_info
Creates named views.
###f5_string_class
####name
The name of the string class to manage.
####members
The string class members.
###f5_user
####name
The user name to manage.
####user_permission
The list of user permissions.
####description
The description for the specified user.
####fullname
The full name for the specified user.
####password
The password for the specified user.
####login_shell
The login shell for the specified user.
###f5_virtualserver
####name
The virtual server name.
####clone_pool
The virtual server clone pool.
####cmp_enabled_state
The virtual server cmp enable state.
Valid options are: STATE_DISABLED, STATE_ENABLED
####connection_limit
The virtual server connection limit.
####connection_mirror_state
The virtual server connection limit.
Valid options are: STATE_DISABLED, STATE_ENABLED
####default_pool_name
The virtual server default pool name.
####destination
The virtual server destination virtual address and port.
####enabled_state
The virtual server state.
####fallback_persistence_profile
The virtual server fallback persistent profile.
####gtm_score
The virtual server gtm score.
####last_hop_pool
The virtual server lasnat64 state.
####nat64_state
The virtual server nat64 state.
Valid options are: STATE_DISABLED, STATE_ENABLED
####protocol
The virtual server protocol.
Valid options are: PROTOCOL_ANY, PROTOCOL_IPV6, PROTOCOL_ROUTING, PROTOCOL_NONE, PROTOCOL_FRAGMENT, PROTOCOL_DSTOPTS, PROTOCOL_TCP, PROTOCOL_UDP, PROTOCOL_ICMP, PROTOCOL_ICMPV6, PROTOCOL_OSPF, PROTOCOL_SCTP
####rate_class
The virtual server rate class.
####persistence_profile
The virtual server persistence profiles.
####profile
The virtual server profiles.
####rule
The virtual server rules. The rule order isn't enforced since F5 API does not provide ability to reorder rules, use irule priority to dictate rule processing order
####snat_type
The virtual server snat type.
Valid options are: SNAT_TYPE_NONE, SNAT_TYPE_TRANSLATION_ADDRESS, SNAT_TYPE_SNATPOOL, SNAT_TYPE_AUTOMAP
####snat_pool
Virtual server snat_pool.
####source_port_behavior
The virtual server source port behavior.
Valid options are: SOURCE_PORT_PRESERVE, SOURCE_PORT_PRESERVE_STRICT, SOURCE_PORT_CHANGE
####translate_address_state
The virtual server translate address state.
Valid options are: STATE_DISABLED, STATE_ENABLED
####translate_port_state
The virtual server translate port state.
Valid options are: STATE_DISABLED, STATE_ENABLED
####type
The virtual server type.
Valid options are: RESOURCE_TYPE_POOL, RESOURCE_TYPE_IP_FORWARDING, RESOURCE_TYPE_L2_FORWARDING, RESOURCE_TYPE_REJECT, RESOURCE_TYPE_FAST_L4, RESOURCE_TYPE_FAST_HTTP, RESOURCE_TYPE_STATELESS
####vlan
The virtual server vlan.
####wildmask
The virtual server wildmask.
##Limitations
- F5 v11.0+
- Nori 2.4
- Savon X
##Development
Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
You can read the complete module contribution guide on the Puppet Labs wiki.