Release 2.0.0 (#156)

.travis.yml.sample

@@ -0,0 +1,29 @@
+---
+language: python
+python: "2.7"
+
+# Use the new container infrastructure
+sudo: false
+
+# Install ansible
+addons:
+  apt:
+    packages:
+    - python-pip
+
+install:
+  # Install ansible
+  - pip install ansible
+
+  # Check ansible version
+  - ansible --version
+
+  # Create ansible.cfg with correct roles_path
+  - printf '[defaults]\nroles_path=../' >ansible.cfg
+
+script:
+  # Basic role syntax check
+  - ansible-playbook tests/test.yml -i tests/inventory --syntax-check
+
+notifications:
+  webhooks: https://galaxy.ansible.com/api/v1/notifications/

README.md

@@ -46,6 +46,11 @@ Each module is documented in docs/modules, you can also look at the
 documentation online at
 <https://paloaltonetworks.github.io/ansible-pan/> under *modules* section
 
+## Developing modules / contributing to codebase
+
+Please see:
+> <http://paloaltonetworks.github.io/ansible-pan/contributing.html>
+
 ## Ansible galaxy role
 
 The Palo Alto Networks Ansible modules project is a collection of Ansible modules to automate configuration and

docs/contributing.md

@@ -0,0 +1,46 @@
+---
+title: Contributing to PANW Ansible modules
+---
+
+# Developing Palo Alto Networks Ansible Modules
+
+(draft)
+
+## Should you develop a module?
+
+Developing PANW Ansible modules is easy, but often it isn't necessary. Before you start writing a new module, ask:
+
+#### Does a similar module already exist?
+
+An existing module may cover the functionality you want. You might just need additional functionality in the existing
+module. If you are not sure feel free to email PANW maintainers.
+
+#### Does a Pull Request already exist?
+
+An existing Pull Request may cover the functionality you want. If someone else has already started developing a similar 
+module, you can review and test it.
+
+* GitHub new module PRs <https://github.com/PaloAltoNetworks/ansible-pan/pulls>
+* Already closed bun not yet released modules <https://github.com/PaloAltoNetworks/ansible-pan/blob/develop/docs/history.md>
+
+If you find an existing PR that looks like it addresses your needs, please provide feedback on the PR. Community feedback 
+speeds up the review and merge process.
+
+#### Should you write multiple modules instead of one module?
+
+The functionality you want may be too large for a single module. You might want to split it into separate modules or
+enhance already existing module.
+
+## Contributing to codebase
+
+If your use case isn't covered by an existing module or an open PR then you're ready to start developing a new module.
+
+In order to do this you need to (draft):
+1. fork develop branch (**NOT MASTER**)
+2. do your changes
+    - update / change module
+    - update [history.md](https://github.com/PaloAltoNetworks/ansible-pan/blob/develop/docs/history.md) with changes
+    - make sure you run code through linter (TBD)
+3. create pull request against **DEVELOP** branch
+    - sometimes it is necessary to rebase your changes. If you need more info on how to this here is a good write-up
+    that can be applied in our case <https://docs.ansible.com/ansible/2.5/dev_guide/developing_rebasing.html>

docs/history.md

@@ -5,11 +5,51 @@ title: History and changelog
 History
 =======
 
+V2.0.1
+------
+
+-   Released: In development
+-   Status: In development
+
+V2.0.0
+------
+
+-   Released: 2018-09-27
+-   Status: Released
+
+*New modules*
+
+- panos\_administrator: Manages Panorama / NGFW administrators
+- panos\_registered\_ip: Use this instead of panos\_dag\_tags
+- panos\_registered\_ip\_facts: Use this instead of panos\_dag\_tags
+- panos\_address\_object: Use this instead of panos\_object
+- panos\_address\_group: Use this instead of panos\_object
+- panos\_service\_object: Use this instead of panos\_object
+- panos\_service\_group: Use this instead of panos\_object
+- panos\_tag\_object: Use this instead of panos\_object
+- panos\_object\_facts: Get facts about objects
+
+*Removed modules*
+
+*Refactored modules*
+
+**Now supporting state / idempotency**
+- panos\_interface
+- panos\_nat\_rule
+- panos\_security\_rule
+
+*Miscellanies / Fixes*
+
+- merged Ansible role repo together with this one
+- https://github.com/PaloAltoNetworks/ansible-pan/issues/44
+- adding beta support for connections lib
+- https://github.com/PaloAltoNetworks/ansible-pan/issues/150
+
 V1.0.8
 ------
 
--   Released: In-development
--   Status: In-development
+-   Released: 2018-09-13
+-   Status: Released
 
 *New modules*
 
@@ -28,6 +68,7 @@ identification, authentication, and encryption (IKEv1 or IKEv2, Phase 1).
 
 -   *panos\_security\_rule* - New [log\_setting]{.title-ref} param added
     to specify the log forwarding profile to be used
+-   re-wrote documentation 
 
 V1.0.7
 ------

docs/index.md

@@ -8,6 +8,7 @@ title: Palo Alto Networks Ansible documentation!
 1. [README](https://github.com/PaloAltoNetworks/ansible-pan/blob/master/README.md)
 2. [Modules](modules.md)
 3. [Examples](examples.md)
-4. [History](history.md)
-5. [Authors](authors.md)
-6. [License](license.md)
+4. [Contributing](controbutiong.md)
+5. [History](history.md)
+6. [Authors](authors.md)
+7. [License](license.md)

examples/fw_address_group.yml

@@ -0,0 +1,36 @@
+---
+- name: Add some address groups to the firewall
+  hosts: my-firewall
+  connection: local
+  gather_facts: False
+
+  tasks:
+  - name: Grab the credentials from ansible-vault
+    include_vars: 'firewall-secrets.yml'
+    no_log: 'yes'
+
+  - name: Create static address group
+    panos_address_group:
+      ip_address: '{{ ip_address }}'
+      username: '{{ username }}'
+      password: '{{ password }}'
+      name: 'Prod-Instances'
+      static_value: ['Test-1.1.1.1', 'Test-2.2.2.2', 'Test-3.3.3.3']
+      tag: ['Prod']
+
+  - name: Create dynamic address group
+    panos_address_group:
+      ip_address: '{{ ip_address }}'
+      username: '{{ username }}'
+      password: '{{ password }}'
+      name: 'SI-Web-EPG'
+      dynamic_value: 'SI-Web-EPG'
+      tag: ['SI']
+
+  - name: Delete address group
+    panos_address_group:
+      ip_address: '{{ ip_address }}'
+      username: '{{ username }}'
+      password: '{{ password }}'
+      name: 'Old-Prod-Instances'
+      state: 'absent'

examples/fw_address_object.yml

@@ -0,0 +1,49 @@
+---
+- name: Add some address objects to the firewall
+  hosts: my-firewall
+  connection: local
+  gather_facts: False
+
+  tasks:
+  - name: Grab the credentials from ansible-vault
+    include_vars: 'firewall-secrets.yml'
+    no_log: 'yes'
+
+- name: Create object 'Test-One'
+  panos_address_object:
+    ip_address: '{{ fw_ip_address }}'
+    username: '{{ fw_username }}'
+    password: '{{ fw_password }}'
+    name: 'Test-One'
+    value: '1.1.1.1'
+    description: 'Description One'
+    tag: ['Prod']
+
+- name: Create object 'Test-Two'
+  panos_address_object:
+    ip_address: '{{ fw_ip_address }}'
+    username: '{{ fw_username }}'
+    password: '{{ fw_password }}'
+    name: 'Test-Two'
+    address_type: 'ip-range'
+    value: '1.1.1.1-2.2.2.2'
+    description: 'Description Two'
+    tag: ['SI']
+
+- name: Create object 'Test-Three'
+  panos_address_object:
+    ip_address: '{{ fw_ip_address }}'
+    username: '{{ fw_username }}'
+    password: '{{ fw_password }}'
+    name: 'Test-Three'
+    address_type: 'fqdn'
+    value: 'foo.bar.baz'
+    description: 'Description Three'
+
+- name: Delete object 'Test-Two'
+  panos_address_object:
+    ip_address: '{{ fw_ip_address }}'
+    username: '{{ fw_username }}'
+    password: '{{ fw_password }}'
+    name: 'Test-Two'
+    state: 'absent'

examples/fw_object_facts.yml

@@ -0,0 +1,28 @@
+---
+- name: Retrieve data about objects from the firewall
+  hosts: my-firewall
+  connection: local
+  gather_facts: False
+
+  tasks:
+  - name: Grab the credentials from ansible-vault
+    include_vars: 'firewall-secrets.yml'
+    no_log: 'yes'
+
+  - name: Retrieve address group object 'Prod'
+    panos_object_facts:
+      ip_address: '{{ fw_ip_address }}'
+      username: '{{ fw_username }}'
+      password: '{{ fw_password }}'
+      name: 'Prod'
+      object_type: 'address-group'
+    register: result
+
+  - name: Retrieve service group object 'Prod-Services'
+    panos_object_facts:
+      ip_address: '{{ fw_ip_address }}'
+      username: '{{ fw_username }}'
+      password: '{{ fw_password }}'
+      name: 'Prod-Services'
+      object_type: 'service-group'
+    register: result

examples/fw_registered_ip.yml

@@ -0,0 +1,46 @@
+---
+- name: Manipulate registered IPs on the firewall
+  hosts: my-firewall
+  connection: local
+  gather_facts: False
+
+  tasks:
+  - name: Grab the credentials from ansible-vault
+    include_vars: 'firewall-secrets.yml'
+    no_log: 'yes'
+
+  - name: Add 'First_Tag' tag to 1.1.1.1 and 1.1.1.2
+    panos_registered_ip:
+      ip_address: '{{ fw_ip_address }}'
+      username: '{{ fw_username }}'
+      password: '{{ fw_password }}'
+      ips: ['1.1.1.1', '1.1.1.2']
+      tags: ['First_Tag']
+      state: 'present'
+
+  - name: Add 'Second_Tag' tag to 1.1.1.1
+    panos_registered_ip:
+      ip_address: '{{ fw_ip_address }}'
+      username: '{{ fw_username }}'
+      password: '{{ fw_password }}'
+      ips: ['1.1.1.1']
+      tags: ['Second_Tag']
+      state: 'present'
+
+  - name: Remove 'Second_Tag' from 1.1.1.1
+    panos_registered_ip:
+      ip_address: '{{ fw_ip_address }}'
+      username: '{{ fw_username }}'
+      password: '{{ fw_password }}'
+      ips: ['1.1.1.1']
+      tags: ['Second_Tag']
+      state: 'absent'
+
+  - name: Remove 'First_Tag' from 1.1.1.2 (will unregister entirely)
+    panos_registered_ip:
+      ip_address: '{{ fw_ip_address }}'
+      username: '{{ fw_username }}'
+      password: '{{ fw_password }}'
+      ips: ['1.1.1.2']
+      tags: ['First_Tag']
+      state: 'absent'

examples/fw_registered_ip_facts.yml

@@ -0,0 +1,25 @@
+---
+- name: Manipulate registered IPs on the firewall
+  hosts: my-firewall
+  connection: local
+  gather_facts: False
+
+  tasks:
+  - name: Grab the credentials from ansible-vault
+    include_vars: 'firewall-secrets.yml'
+    no_log: 'yes'
+
+  - name: Get facts for all registered IPs
+    panos_registered_ip_facts:
+      ip_address: '{{ fw_ip_address }}'
+      username: '{{ fw_username }}'
+      password: '{{ fw_password }}'
+    register: registered_ip_facts
+
+  - name: Get facts for specific tag
+    panos_registered_ip_facts:
+      ip_address: '{{ fw_ip_address }}'
+      username: '{{ fw_username }}'
+      password: '{{ fw_password }}'
+      tags: ['First_Tag']
+    register: first_tag_registered_ip_facts

examples/fw_service_group.yml

@@ -0,0 +1,26 @@
+---
+- name: Add some service groups to the firewall
+  hosts: my-firewall
+  connection: local
+  gather_facts: False
+
+  tasks:
+  - name: Grab the credentials from ansible-vault
+    include_vars: 'firewall-secrets.yml'
+    no_log: 'yes'
+
+- name: Create service group 'Prod-Services'
+  panos_service_group:
+    ip_address: '{{ ip_address }}'
+    username: '{{ username }}'
+    password: '{{ password }}'
+    name: 'Prod-Services'
+    value: ['ssh-tcp-22', 'mysql-tcp-3306']
+
+- name: Delete service group 'Prod-Services'
+  panos_service_group:
+    ip_address: '{{ ip_address }}'
+    username: '{{ username }}'
+    password: '{{ password }}'
+    name: 'Prod-Services'
+    state: 'absent'