Concepts
The names that ShellGraph uses, and how they relate to each other.
Names
| Name | Meaning |
|---|---|
| Environment | A group of VLANs. Each Environment has one map. Examples: “Production”, “Staging”. |
| VLAN | A CIDR that the collector scans, with an SSH port and a credential. A VLAN belongs to one Environment. |
| Credential | An SSH user, a private key, an optional passphrase and the “use sudo” setting. Many VLANs can use the same credential. |
| Collector | The shellgraph program. It scans one VLAN and sends one report. |
| Collector token | A secret that lets one collector use the server. |
| Scan | One run of the collector on one VLAN. |
| Host | A server that answered and accepted the credential. ShellGraph identifies a host by its /etc/machine-id and its hostname. |
| Service | A program on a host. The name comes from the container name, or from the systemd unit, or from the process name. |
| Endpoint | A port where a service listens (listen endpoint), or a destination that a service calls. |
| Ignore rule | A name pattern. A service with a name that matches does not show on the map. |
| Tag rule | A hostname pattern that gives a tag. The map puts the hosts with the same tag in one group. |
| Role | admin (all operations) or viewer (read only). The role comes from the LDAP or OIDC groups of the user. |
Why a map shows an Environment
The services of one application are often in many VLANs, for example the load balancers in 10.0.10.0/24 and the databases in 10.0.20.0/24. On a map of the first VLAN, the databases would be bare addresses in the Outside environment group, without their services. An Environment joins the VLANs. One map then shows all the calls.
Why tags
Two hundred hosts in a random order make a map that nobody can read. Most companies name their servers with a pattern, such as lb01 or db-02. Tag rules read that pattern and put related hosts near each other, so you do not tag each host by hand.
Inbound and outbound
- A connection to a port where the service listens is inbound. The other side is a client.
- All other connections are outbound. The service calls the other side.
The map shows each connection one time, as an arrow from the caller to the port. How the collector works tells how the collector decides the direction.