Permalink
Browse files

Agent Proxy docs moved to Enstratius

  • Loading branch information...
1 parent 8a9c12d commit dfab33bc6f56f5b920cd04c1dcae72b08adbcbca @timf timf committed Mar 15, 2013
Showing with 65 additions and 65 deletions.
  1. +29 −29 agent/proxy/background.rst
  2. +10 −10 agent/proxy/installation.rst
  3. +11 −11 agent/proxy/operations.rst
  4. +3 −3 agent/proxy/proxy.rst
  5. +12 −12 agent/proxy/registration.rst
@@ -3,52 +3,52 @@
Background
----------
-Without the ability to interact with an enStratus agent on your cloud resources,
-many automation and security features are not supported. The enStratus agent
+Without the ability to interact with an Enstratius agent on your cloud resources,
+many automation and security features are not supported. The Enstratius agent
proxy is a service installed on a node (or set of nodes) running on a cloud or
-on-premises network that allows enStratus to contact resources that would
+on-premises network that allows Enstratius to contact resources that would
otherwise be inaccessible.
There are two classes of problems that agent proxies solve:
-* The cloud API endpoint is accessible from enStratus but VMs are not.
+* The cloud API endpoint is accessible from Enstratius but VMs are not.
* One cloud API, multiple VMs assigned the same local IP address.
There are problems agent proxies cannot solve:
-* The cloud API endpoint is inaccessible from enStratus.
-* enStratus is inaccessible from the VM instances even through a dedicated proxy.
+* The cloud API endpoint is inaccessible from Enstratius.
+* Enstratius is inaccessible from the VM instances even through a dedicated proxy.
Agent Interactions
~~~~~~~~~~~~~~~~~~
Before discussing the network problems in detail, a quick review of how
cloud resources with backups and automation normally work:
-1. enStratus starts and monitors a new VM via a cloud API.
+1. Enstratius starts and monitors a new VM via a cloud API.
2. The agent on the new VM instance starts (normally via the init.d mechanism or equivalent).
3. The agent initiates the handshake process with the configured URL.
-4. The handshake is negotatied between agent and enStratus.
+4. The handshake is negotatied between agent and Enstratius.
* A part of this handshake is especially important to the problems below: some of the information used to recognize a new VM instance trying to handshake are the IP address and cloud-given instance ID that the agent can assert about its host VM.
5. After the handshake is complete, the agent now listens for instructions
- asynchronously and also periodically reaches out to enStratus of its own
+ asynchronously and also periodically reaches out to Enstratius of its own
accord.
.. figure:: ./images/agent-overview.png
:align: center
-These communications to and from the agent are necessary for enStratus to
+These communications to and from the agent are necessary for Enstratius to
provide advanced automation, backup, user provisioning, logging, and intrusion
detection capabilities.
Problem: Cloud accessible, VMs inaccessible
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There are situations when enStratus can connect to a cloud API but has no route
-to contact the VM's enStratus agent for automation. An example of this case is
-when you want to use enStratus with a private cloud but there is no route to
+There are situations when Enstratius can connect to a cloud API but has no route
+to contact the VM's Enstratius agent for automation. An example of this case is
+when you want to use Enstratius with a private cloud but there is no route to
the VMs which are on a private, but NAT'd network. As depicted here:
.. figure:: ./images/proxy-problems1.png
@@ -77,35 +77,35 @@ The following diagram shows an example of two VMs with the same local IP:
Consider this situation. When each agent initializes, they have no problem
contacting the dispatcher to initiate the handshake (the green arrows back to
-enStratus). Two problems arise at that point though:
+Enstratius). Two problems arise at that point though:
1. For private clouds where the agent cannot reflect and report on its VM
instance ID, only the reported private IP is sent in the handshake and used by
-enStratus for correlation. Since both communications are seen as coming from the
+Enstratius for correlation. Since both communications are seen as coming from the
same gateway (5.5.5.5), there is nothing to distinguish the two VMs (except
perhaps where each VM is in their expected lifecycle but this is tenuous).
-2. As in a previous example, enStratus has no direct route back to the VMs here.
-But even if there were some channel open, how would enStratus be able to contact
+2. As in a previous example, Enstratius has no direct route back to the VMs here.
+But even if there were some channel open, how would Enstratius be able to contact
one 10.0.0.2 and not the other 10.0.0.2 without some supporting, topology-aware
mechanism?
(Note that this is not unique to the public internet case, the same situations
can occur in multi-network situations for on-premises installs.)
-To further complicate things, enStratus may be working against multiple private
+To further complicate things, Enstratius may be working against multiple private
clouds that are employing the same private address space.
Agent Proxy
~~~~~~~~~~~
-An enStratus agent is configured to handshake with a certain service endpoint.
+An Enstratius agent is configured to handshake with a certain service endpoint.
To employ the agent proxy, one change is necessary: point to a new service
endpoint.
-The agent proxy acts like enStratus to the agent: the service signature is
+The agent proxy acts like Enstratius to the agent: the service signature is
identical. The agent proxy is stateless, however, and simply forwards the
-traffic "upstream" to enStratus. For the opposite direction, enStratus contacts
+traffic "upstream" to Enstratius. For the opposite direction, Enstratius contacts
the agent proxy as if it was a regular agent interaction - but with some
metadata about where it should be routed.
@@ -118,9 +118,9 @@ The agent proxy:
* is a service you run on a node nearer to the cloud resources in question.
* has the same service signature that agents normally talk to: agents can not
- tell the difference between an agent proxy and enStratus proper.
+ tell the difference between an agent proxy and Enstratius proper.
* requires network access to the cloud resources in question.
-* requires network access to enStratus, but only one ``ip:port`` firewall
+* requires network access to Enstratius, but only one ``ip:port`` firewall
rule is required in each direction.
* can be deployed behind a load balancer for high availability and extreme load.
* does not require any database: it is completely stateless.
@@ -130,16 +130,16 @@ The agent proxy:
Handshake Implications
~~~~~~~~~~~~~~~~~~~~~~
-In the normal handshake process, the initial agent to enStratus SSL connection
+In the normal handshake process, the initial agent to Enstratius SSL connection
(for the 'handshake' operation) provides a token and an encryption key that
were generated by the agent. Because the SSL channel is itself encrypted, this
-allows enStratus to be confident it is able to encrypt/sign agent calls using
+allows Enstratius to be confident it is able to encrypt/sign agent calls using
the provided encryption key and it will only be able to be decrypted by the
original caller (who may be a spoofer themselves, but this scheme at least
prevents man in the middle attacks).
In the proxy scheme, the handshake operation traverses multiple SSL sessions,
-and therefore enStratus can only be confident it is able to encrypt/sign agent
+and therefore Enstratius can only be confident it is able to encrypt/sign agent
calls using the provided encryption key and it will only be able to be decrypted
by the original caller and any agent proxy in between.
@@ -150,11 +150,11 @@ If the networks from the VM instances to the agent proxy are very tightly
locked down, turning off the agent's SSL certificate validation could be an
option. Otherwise it is recommended that the agent use certificate validation
during the initiation of the agent proxy SSL session, just as the same is
-recommended for agent to enStratus connections without proxies.
+recommended for agent to Enstratius connections without proxies.
The reverse, however, is not required. The agent proxy does not need to validate
-the SSL certificate of the agent and enStratus does not need to validate the SSL
-certificate of the agent proxy. The same is true of enStratus initiated
+the SSL certificate of the agent and Enstratius does not need to validate the SSL
+certificate of the agent proxy. The same is true of Enstratius initiated
connections directly to agents without proxies.
This is because communication initiated in this direction uses SSL for wire
@@ -3,7 +3,7 @@
Installation
------------
-Before letting enStratus know about an agent proxy (:ref:`Registration
+Before letting Enstratius know about an agent proxy (:ref:`Registration
<agent_proxy_registration>`), you must get it running on a node.
The agent proxy is packaged as a war file with all dependencies included. The
@@ -27,8 +27,8 @@ file which is the application, and ``agent-proxy.sh`` which is what you run.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the ``agentproxy.properties`` file, find ``upstreamHostPort``. This is set to
-``provisioning.enstratus.com:3302`` by default which is the enStratus SaaS
-handshake endpoint. If you are working with an alternate enStratus installation,
+``provisioning.enstratus.com:3302`` by default which is the Enstratius SaaS
+handshake endpoint. If you are working with an alternate Enstratius installation,
use the host:port combination given to you.
Also in this file is ``agentProxyId``. For this configuration, pick a unique ID
@@ -39,7 +39,7 @@ random string is better.
Also in this file is ``disableUpstreamValidation``. You will want to change this
to ``true`` for initial setup and testing. If left with its default value
``false``, the agent proxy will expect to validate the SSL chain of the upstream
-enStratus installation when it relays agent handshakes. During setup and
+Enstratius installation when it relays agent handshakes. During setup and
testing, you should remove this security barrier to make sure everything else is
working first.
@@ -97,17 +97,17 @@ to be in the agent proxy directory for it to run.
./agent-proxy.sh
-5. Register the agent with enStratus
+5. Register the agent with Enstratius
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Instructions to register the agent with enStratus are in the
+Instructions to register the agent with Enstratius are in the
:ref:`Registration <agent_proxy_registration>` section.
6. Test the agent proxy
~~~~~~~~~~~~~~~~~~~~~~~
-The enStratus :ref:`agent <agent>` now needs to be configured to handshake via
-this server instead of the enStratus installation. To reconfigure it, find this
+The Enstratius :ref:`agent <agent>` now needs to be configured to handshake via
+this server instead of the Enstratius installation. To reconfigure it, find this
file on the VM:
.. code-block:: text
@@ -126,9 +126,9 @@ not commented out). For example:
Now you will need to make a new machine image. When it is launched, this IP:port
combination will be used to handshake, not the default address. The agent does
-not realize it is talking to an agent proxy and not enStratus proper.
+not realize it is talking to an agent proxy and not Enstratius proper.
To test that everything is communicating, look at the logging (testing
-communication from the VM to enStratus) and then try to add a user to the VM
+communication from the VM to Enstratius) and then try to add a user to the VM
(testing the opposite direction).
@@ -17,7 +17,7 @@ Configurations
The agent proxy requires configuration as part of the installation process.
-In particular the **upstream enStratus URL**, a **unique ID** string, and
+In particular the **upstream Enstratius URL**, a **unique ID** string, and
an **SSL certificate** need to be set correctly on a per-deployment basis.
An assistance script is provided for quick creation of self-signed certificates.
@@ -32,8 +32,8 @@ documentation.
Registration
~~~~~~~~~~~~
-Once started, the proxy needs to be registered in the enStratus application. If
-the server it is running on is already detected/managed by enStratus, there is a
+Once started, the proxy needs to be registered in the Enstratius application. If
+the server it is running on is already detected/managed by Enstratius, there is a
simple UI action to register it as a proxy (it assumes port 2002). Otherwise,
you will need to enter the appropriate host:port into a dialogue to register.
There is also REST API support for registration (and deregistration).
@@ -44,7 +44,7 @@ Registration requires the proxy to be running, there is an initial handshake
that occurs. The proxy may be restarted at will after this: if it misses a
message, there will potentially be some automation slowdown but the message will
be repeated in time (this is very similar to an agent being out of contact due
-to a cloud network issue - the agent and enStratus are resilient to this).
+to a cloud network issue - the agent and Enstratius are resilient to this).
Load Balancing
~~~~~~~~~~~~~~
@@ -60,8 +60,8 @@ Networks/Forwarding
By default, the Agent Proxy accepts traffic on port 2002. The following diagram
outlines a typical firewall/port-forwarding scheme to enable the agent proxy
-running at a site with an offsite enStratus (for on-premises installations this
-is analogous to enStratus being installed on a separate site network from IaaS,
+running at a site with an offsite Enstratius (for on-premises installations this
+is analogous to Enstratius being installed on a separate site network from IaaS,
as is common):
.. figure:: ./images/proxy-overview2.png
@@ -80,16 +80,16 @@ forwarding traffic to ``10.1.2.3``, port ``2002``:
:align: center
In this situation, the VM instances only need to contact ``10.1.2.3``, port
-``2002``, not the enStratus application running on the public internet (in the
+``2002``, not the Enstratius application running on the public internet (in the
case of an on-premises deployment, this is analagous to whatever custom site
-network enStratus runs on).
+network Enstratius runs on).
The agent proxy needs to be able to contact the VM instances at will (either
by virtue of being on the same subnet or by the proper routing configurations).
-enStratus needs to be able to reach ``4.3.2.1``, port ``2002`` in this example.
+Enstratius needs to be able to reach ``4.3.2.1``, port ``2002`` in this example.
-And the agent proxy needs to be able to reach enStratus at ``8.7.6.5``,
+And the agent proxy needs to be able to reach Enstratius at ``8.7.6.5``,
port ``3302``.
Limiting Access
@@ -100,7 +100,7 @@ traffic from valid source IP ranges**.
For example, using the setup and addresses in the last section, the firewall
rule that forwards ``4.3.2.1:2002`` to ``10.1.2.3:2002`` should be enhanced to
-only forward traffic from enStratus source IPs.
+only forward traffic from Enstratius source IPs.
The acceptable ranges include any source IPs that dispatcher, monitor, or
worker traffic appears from. This is especially important in the case where this
@@ -3,10 +3,10 @@
Agent Proxy
-----------
-Without the ability to interact with an enStratus agent on your cloud resources,
-many automation and security features are not supported. The enStratus agent
+Without the ability to interact with an Enstratius agent on your cloud resources,
+many automation and security features are not supported. The Enstratius agent
proxy is a service installed on a node (or set of nodes) running on a cloud or
-on-premises network that allows enStratus to contact resources that would
+on-premises network that allows Enstratius to contact resources that would
otherwise be inaccessible.
If you are new to the agent proxy, see the :ref:`Background
@@ -3,7 +3,7 @@
Registration
------------
-After an agent proxy is running, enStratus will not recognize agent traffic
+After an agent proxy is running, Enstratius will not recognize agent traffic
from it until it has been registered.
This guide shows you how to register (and deregister) agent proxies using the
@@ -13,7 +13,7 @@ documentation, in particular you have installed an agent proxy following the
There are two different ways to register agent proxies:
-1. Selecting a server because the agent proxy is running on a node that has been detected or launched by enStratus. See `Registering via managed resource`_ below.
+1. Selecting a server because the agent proxy is running on a node that has been detected or launched by Enstratius. See `Registering via managed resource`_ below.
2. Entering an arbitrary IP:port to handshake with. See `Registering via external resource`_ below.
At the end of this page is also `Deregistering`_ information.
@@ -22,7 +22,7 @@ Registering via managed resource
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use this method if the agent proxy is running on a node that has been detected
-or launched by enStratus.
+or launched by Enstratius.
Navigate to the ``Agent Proxies`` screen:
@@ -41,14 +41,14 @@ server.
When you are ready to proceed, click the ``Begin Registration`` button.
-enStratus will now contact the agent proxy service. It will call on a special
-operation for handshaking and then the enStratus UI will display the ID that
+Enstratius will now contact the agent proxy service. It will call on a special
+operation for handshaking and then the Enstratius UI will display the ID that
the agent proxy was configured with (or give you an error such as "connection
refused").
If this ID is accurate, click ``Confirm`` and the agent proxy will be registered.
You will now see a status message ``Agent proxy has been associated``. Traffic
-relayed from this proxy will now be accepted by enStratus.
+relayed from this proxy will now be accepted by Enstratius.
You may need to click the ``Reload`` button on the ``Agent Proxies`` screen before
the new proxy is listed in the table.
@@ -60,7 +60,7 @@ Registering via external resource
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use this method if the agent proxy is running on a node that has not been
-detected or launched by enStratus. Or if the IP:port coordinates are manually
+detected or launched by Enstratius. Or if the IP:port coordinates are manually
set up (for example, you have manually created a port forwarding rule to a
private cloud resource).
@@ -81,8 +81,8 @@ look like ``4.3.2.1:1234``.
When you are ready to proceed, click the ``Begin Registration`` button.
-enStratus will contact the agent proxy service. It will call on a special
-operation for handshaking and then the enStratus UI will display the ID that
+Enstratius will contact the agent proxy service. It will call on a special
+operation for handshaking and then the Enstratius UI will display the ID that
the agent proxy was configured with (or give you an error such as "connection
refused").
@@ -94,7 +94,7 @@ If this ID and region/network is all accurate, click ``Confirm`` and the agent
proxy will be registered.
You will now see a status message ``Agent proxy has been associated``. Traffic
-relayed from this proxy will now be accepted by enStratus.
+relayed from this proxy will now be accepted by Enstratius.
You may need to click the ``Reload`` button on the ``Agent Proxies`` screen before
the new proxy is listed in the table.
@@ -111,10 +111,10 @@ Navigate to the ``Agent Proxies`` screen:
:align: center
Find the agent proxy in the list that you wish to deactivate. Proxies are listed
-here with their enStratus numeric ID (the ``ID`` column) and the unique ID that
+here with their Enstratius numeric ID (the ``ID`` column) and the unique ID that
you configured the agentproxy with (the ``Proxy ID`` column). If you registered
the proxy using an arbitrary IP:port, that will be listed in the ``Address``
-column. If you registered the proxy using a enStratus-managed server, that
+column. If you registered the proxy using a Enstratius-managed server, that
server ID will be listed in the ``Server`` column.
Once you have decided which agent proxy to deregister, click on ``actions``

0 comments on commit dfab33b

Please sign in to comment.