3.0 (#50)

* First 3.0 Commit

Co-authored-by: Josh Saul <[email protected]>
Co-authored-by: Gor Poghosyan <[email protected]>
Co-authored-by: Arsen Arakelyan <[email protected]>

Author: 3 people

README.md

@@ -0,0 +1,11 @@
+# Netris User Documentation
+
+This repository stores external documentation related to the Netris Automatic NetOps software solution.
+
+More Information:
+
+[email protected]
+
+https://netris.ai
+
+Current docs are available at: https://netris.ai/docs

SoftGate-agent-installation.rst

@@ -2,28 +2,28 @@
   :description: Netris SoftGate Agent Installation
 
 ***********************************
-Netris SoftGate agent installation
+Netris SoftGate Agent Installation
 ***********************************
-Minimal hardware requirements
+Minimum Hardware Requirements
 =============================
 * 2 x Intel Silver CPU
 * 96 GB RAM
 * 300 GB HDD
 * Nvidia Mellanox Connect-X 5 SmartNIC card
 
-BIOS configuration
+BIOS Configuration
 ==================
-The following are some recommendations on BIOS settings. Different vendors will have different BIOS naming so the following is mainly for reference:
+The following are some recommendations for BIOS settings. Different vendors will have different BIOS naming so the following is mainly for reference:
 
-* Before starting consider resetting all BIOS settings to their defaults.
-* Disable all power saving options such as: Power performance tuning, CPU P-State, CPU C3 Report and CPU C6 Report.
-* Select Performance as the CPU Power and Performance policy.
-* Disable Turbo Boost to ensure the performance scaling increases with the number of cores.
-* Set memory frequency to the highest available number, NOT auto.
-* Disable all virtualization options when you test the physical function of the NIC, and turn off VT-d.
-* Disable Hyper-Threading.
+* Before starting consider resetting all BIOS settings to their defaults
+* Disable all power saving options such as: Power performance tuning, CPU P-State, CPU C3 Report and CPU C6 Report
+* Select Performance as the CPU Power and Performance policy
+* Disable Turbo Boost to ensure the performance scaling increases with the number of cores
+* Set memory frequency to the highest available number, NOT auto
+* Disable all virtualization options when you test the physical function of the NIC, and turn off VT-d
+* Disable Hyper-Threading
 
-Software installation
+Software Installation
 =====================
 Requires freshly installed Ubuntu Linux 18.04 and network connectivity with your Netris Controller over the out-of-band management network.
 
@@ -35,7 +35,7 @@ Requires freshly installed Ubuntu Linux 18.04 and network connectivity with your
 
   echo -e 'Acquire::http::Proxy "http://<Your Netris Controller address>:3128";\nAcquire::https::Proxy "http://<Your Netris Controller address>:3128";' | sudo tee -a /etc/apt/apt.conf.d/netris-proxy
 
-2. Config the apt for Mellanox repository.
+2. Config the apt for Nvidia Mellanox repository.
 
 .. code-block:: shell-session
 
@@ -57,15 +57,15 @@ Requires freshly installed Ubuntu Linux 18.04 and network connectivity with your
 
   sudo apt-get update && sudo apt-get install mlnx-ofed-dpdk
 
-5. Install Netris agent package and dependencies, including specific Linux Kernel version.
+5. Install Netris Agent package and dependencies, including specific Linux Kernel version.
 
 .. code-block:: shell-session
 
   sudo apt-get install netris-dpdk-mlnx
 
 6. Configure Management IP address
 
-Configure out of band management IP address. In case Netris Controller is not in the same OOB network then add a route to Netris Controller. No default route or other IP addresses should be configured. 
+Configure out-of-band management IP address. If the Netris Controller is not in the same OOB network then add a route to Netris Controller. No default route or other IP addresses should be configured. 
 
 .. code-block:: shell-session
 
@@ -97,7 +97,6 @@ Configure out of band management IP address. In case Netris Controller is not in
 | **--controller** - IP address or domain name of Netris Controller. 
 | **--hostname** - Specify the hostname for the current switch, this hostname should match the name defined for particular switch in the Controller..
 | **--lo** - IP address for the loopback interface, as it is defined in the controller.
-| **--node-prio - brief explanation of node priority goes here**
 |
 | Run netris-setup.
 
@@ -123,17 +122,13 @@ Example: Running netris-setup
   └── └── * Setup Grub Config
   * Update Grub
   └── 
-
 | *** ATTENTION: You must reboot SoftGate to complete the installation 
 | netris@ubuntu:~$ 
-|
 
-8. Reboot the server
+1. Reboot the server
 
 .. code-block:: shell-session
 
   sudo reboot
 
-When server boots up, you should see it’s heartbeat status in Net→Inventory
-
-
+When server completes the reboot process, you should see it’s heartbeat status in Net→Inventory

_static/styles.css

@@ -2,10 +2,7 @@ pre.literal-block {
     white-space: pre;
     margin: 0 !important;
     padding: 12px 12px !important;
-    font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console",
-        "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono",
-        "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier,
-        monospace;
+    font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier, monospace;
     font-size: 12px;
     display: block;
     overflow: auto;
@@ -28,7 +25,7 @@ pre.literal-block {
     border-color: #f9556d;
 }
 
-.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a {
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a {
     background: #ffffff;
 }
 
@@ -39,11 +36,11 @@ pre.literal-block {
 
 .wy-menu-vertical a:hover,
 .wy-menu-vertical li.current,
-.wy-menu-vertical li.current > a {
+.wy-menu-vertical li.current>a {
     background-color: #ffffff !important;
 }
 
-.wy-menu-vertical li.current > a {
+.wy-menu-vertical li.current>a {
     color: #000000 !important;
     border: none !important;
 }
@@ -76,7 +73,7 @@ pre.literal-block {
 }
 
 .underscore-transition,
-.rst-other-versions > a {
+.rst-other-versions>a {
     font-family: Montseratt;
 }
 
@@ -87,9 +84,9 @@ pre.literal-block {
 .underscore-transition,
 .wy-breadcrumbs li:first-child,
 .wy-breadcrumbs li:last-child,
-.rst-other-versions > a,
+.rst-other-versions>a,
 .toctree-wrapper a,
-footer > a {
+footer>a {
     color: #01358d !important;
     position: relative;
 }
@@ -98,9 +95,9 @@ footer > a {
 .wy-menu-vertical a::before,
 .wy-breadcrumbs li:first-child::before,
 .wy-breadcrumbs li:last-child::before,
-.rst-other-versions > a::before,
+.rst-other-versions>a::before,
 .toctree-wrapper a::before,
-footer > a::before {
+footer>a::before {
     box-sizing: inherit;
     content: "";
     position: absolute;
@@ -117,9 +114,9 @@ footer > a::before {
 .wy-menu-vertical a:hover::before,
 .wy-breadcrumbs li:first-child:hover::before,
 .wy-breadcrumbs li:last-child:hover::before,
-.rst-other-versions > a:hover::before,
+.rst-other-versions>a:hover::before,
 .toctree-wrapper a:hover::before,
-footer > a:hover::before {
+footer>a:hover::before {
     width: 100%;
     border-top-color: #f9556d;
     border-right-color: #f9556d;
@@ -189,3 +186,19 @@ footer > a:hover::before {
     cursor: pointer;
     margin-right: 25px;
 }
+
+.with-shadow {
+    box-shadow: rgba(50, 50, 93, 0.25) 0px 6px 12px -2px, rgba(0, 0, 0, 0.3) 0px 3px 7px -3px;
+}
+
+.centered {
+    text-align: center;
+}
+
+.wy-table-responsive table td {
+    white-space: normal !important;
+}
+
+.wy-table-responsive {
+    overflow: visible !important;
+}

acls.rst

@@ -0,0 +1,113 @@
+.. meta::
+    :description: Access Control Lists (ACLs)
+    
+##########################
+Access Control Lists (ACL)
+##########################
+Netris supports ACLs for switch network access control. (ACL and ACL2.0) ACL is for defining network access lists in a source IP: Port, destination IP: Port format. ACL2.0 is an object-oriented service way of describing network access.
+
+Both ACL and ACL2.0 services support tenant/RBAC based approval workflows. Access control lists execute in switch hardware providing line-rate performance for security enforcement. It’s important to keep in mind that the number of ACLs is limited to the limited size of TCAM of network switches. 
+
+Screenshot: TCAM utilization can be seen under Net→Inventory
+
+.. image:: images/TCAM.png
+    :align: center
+    :class: with-shadow
+    
+Netris is applying several optimization algorithms to minimize the usage of TCAM while achieving the user-defined requirements.  
+
+ACL Default Policy
+------------------
+The ACL default policy is to permit all hosts to communicate with each other.  You can change the default policy on a per Site basis by editing the Site features under Net→Sites. Once the “ACL Default Policy” is changed to “Deny,” the given site will start dropping any traffic unless specific communication is permitted through ACL or ACL2.0 rules.
+
+Example: Changing “ACL Default Policy” for the site “siteDefault”.
+
+.. image:: images/siteDefault.png
+    :align: center
+    :class: with-shadow
+    
+
+ACL Rules
+---------
+ACL rules can be created, listed, edited, approved under Services→ACL.
+
+Description of ACL fields.
+General
+
+* **Name** - Unique name for the ACL entry.
+* **Protocol** - IP protocol to match.
+
+  * All - Any IP protocols.
+  * IP - Specific IP protocol number.
+  * TCP - TCP.
+  * UDP - UDP.
+  * ICMP ALL - Any IPv4 ICMP protocol.
+  * ICMP Custom - Custom IPv4 ICMP code.
+  * ICMPv6 ALL - Any IPv6 ICMP protocol. 
+  * ICMPv6 Custom - Custom IPv6 ICMP code.
+  
+* **Active Until** - Disable this rule at the defined date/time. 
+* **Action** - Permit or Deny forwarding of matched packets.
+* **Established/Reverse** - For TCP, also match reverse packets except with TCP SYN flag. For non-TCP, also generate a reverse rule with swapped source/destination.  
+
+Source/Destination - Source and destination addresses and ports to match.
+
+* **Source** IPv4/IPv6 - IPv4/IPv6 address.
+* **Ports Type**
+
+  * Port Range - Match on the port or a port range defined in this window.
+  * Port Group - Match on a group of ports defined under Services→ ACL Port Group.
+  
+* **From Port** - Port range starting from.
+* **To Port** - Port range ending with.
+
+* **Comment** - Descriptive comment, commonly used for approval workflows.
+
+* **Check button** - Check if Another ACL on the system already permits the described network access.
+
+Example: Permit hosts in 10.0.3.0/24 to access hosts in 10.0.5.0/24 by SSH, also permit the return traffic (Established).
+
+.. image:: images/action_permit.png
+    :align: center
+    :class: with-shadow
+      
+Example: “Check” shows that requested access is already provided by a broader ACL rule.
+
+.. image:: images/ACL_rule.png
+    :align: center
+    :class: with-shadow
+        
+ACL Approval Workflow
+---------------------
+When one tenant (one team) needs to get network access to resources under the responsibility of another tenant (another team), an ACL can be created but will activate only after approval of the tenant responsible for the destination address resources. See the below example.
+
+Example: User representing QA_tenant is creating an ACL where source belongs to QA_tenant, but destination belongs to the Admin tenant.
+
+.. image:: images/ACL_approval.png
+    :align: center
+    :class: with-shadow
+    
+Screenshot: ACL stays in “waiting for approval” state until approved.
+    
+.. image:: images/waiting_approval.png
+    :align: center
+    :class: with-shadow
+    
+Screenshot: Users of tenant Admin, receive a notification in the GUI, and optionally by email. Then one can review the access request and either approve or reject it.
+
+.. image:: images/approve_reject.png
+    :align: center
+    :class: with-shadow
+    
+Screenshot: Once approved, users of both tenants will see the ACL in the “Active” state, and soon Netris Agents will push the appropriate config throughout the switch fabric.
+
+.. image:: images/ACL_active.png
+    :align: center
+    :class: with-shadow
+    
+ACL Processing Order
+--------------------
+#. User-defined Deny Rules
+#. User-defined Permit Rules
+#. Deny the rest
+

conf.py

@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.9'
+version = '3.0'
 # The full version, including alpha/beta/rc tags.
-release = 'Netris v2.9'
+release = 'Netris v3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -143,7 +143,7 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = 'Netris 2.9 Documentation'
+html_title = 'Netris 3.0 Documentation'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None