Document your lab from the devices, not from memory

short · 45 min · Objective 3.1

Task

Produce the four documents the objective names — physical diagram, logical diagram, IP address plan and a service inventory — for your own lab, deriving every entry from a command rather than from what you think you configured. The gap between the two is the reason documentation drifts.

Steps

  1. Physical diagram. On each VM, run ip -br link show and record every interface with its MAC address and state. Draw the boxes and the links between them, labelling each link with the interface names at both ends.
  2. Logical diagram. Run ip -br addr show and ip route show on each host. Draw the subnets as clouds, the router between them, and mark each host with its address and gateway. This diagram has no cables on it and that is the point — logical and physical answer different questions.
  3. IP address plan. Record every address in use, what holds it, whether it is static or from DHCP, and what is reserved. Include the ranges you are deliberately keeping free.
  4. Service inventory. On each host, sudo ss -tlnp lists every listening service with its port and process. Record them. Anything listening you cannot explain is either a finding or a service you forgot you installed — both worth knowing.
  5. Compare what you documented against what you thought was configured. Write down every discrepancy. On a lab you built last week there will be at least one.

Verify

ip -br link show
ip -br addr show
ip route show
sudo ss -tlnp | awk 'NR==1 || /LISTEN/'

Every line of those four outputs must appear somewhere in your four documents, and every line of your documents must be traceable to one of those outputs. Documentation that contains something no command produced is documentation that describes an intention.

Notes

The discrepancy list from step 5 is the real output of this lab. In a production network that list is usually long, and each item is either drift (the device changed and the document did not) or an error (the document was wrong from the start).

The fifth document worth mentioning is the rack diagram and the sixth is the cable map, and both matter more than they sound. A network you can diagram logically but cannot find physically is one where every hardware fault starts with an hour of tracing.

Keep these four documents. The change-management lab asks you to update them properly after a change, which is where documentation either stays true or starts its slow drift into fiction.