How do you document a network?

Question

I'm not sure how to ask this question, since I'm not in the field. Say you're a network admin and you leave your job. How does the new guy know where to start?

Answer 1

It depends on the size of the network, number of users, number of nodes (computers, servers, printers, etc.) and the size of your IT staff, among other things.

It also depends on your goal. Are you documenting the network for training and maintenance purposes, insurance/loss prevention, etc?

Personally, I document my networks in such a way that I know I can derive any missing information based on what is documented. From a practical stance, there is a point of diminishing returns when your documentation gets too granular.

A good rule of thumb I use is that there should be documentation in a known location that is thorough enough that if I get hit by a bus tonight, another administrator can keep the core network running while he/she fills in the missing pieces over the next few days/weeks.

Here is an overview of what I think is most important about one of my networks. For the record this is a Windows-only shop with about 100 users and 5 offices.

• Administrator credentials for all servers. Obviously this should be kept secure.
• IP Addresses and NetBIOS names for any node on the network with a static IP address, including servers, workstations, printers, firewalls, routers, switches, etc.
• Basic server hardware information, such as Service tags or equivalent, total disk capacity, total RAM, etc.
• Major roles of each server, such as Domain Controller, File Server, Print Server, Terminal Server, etc.
• Location of backup tapes/drives.
• Information about the account numbers and credentials for services like remote office voice and data providers.
• External DNS for websites and routing.

If there was anything strange about a setup or workflow that would not be immediately obvious to a new administrator, I would write a short "brief" about it as well.

Answer 2

I find it's best to incorporate all of the following:

• Prose: A general overview in paragraph form, which helps with initial big picture and also can describe evolution over time
• Tables: Tabular lists, either address-keyed, environment-keyed, or machine-keyed (preferably all of the above)
• Diagrams: Definitely need diagrams with multiple levels of detail. On any decent size network, it's just impossible to sanely capture it all on one page and make it easily digestible. You want one diagram at the global level, with infrastructure devices (routers, switches, tunnel endpoints, etc.), and another several for the compute resources fronted by each of those routers or endpoints.

Additional notes about diagrams... Geographic distribution is an easy way to segment, but you also need logical views based on installation function. Also, label like crazy, making full use of typefaces and colors.

Answer 3

Kyle's answer is great advice. At a bare minimum though, you could probably get away with listing out:

• Servers (include hostnames, IPs, and roles)
• Network hardware (switches, routers, firewalls)
• Master password archives (domain passwords, admin passwords)
• A rough document outlining network policies and any strange setups (include here any outliers such as machines which aren't part of the domain(s))

Answer 4

Where I work - we faced the same problem when I first started here. As the number of servers and services increases, you find more and more out-of-date documentation, and with that comes the inevitable attitude for staff to not trust documentation, at least technical documentation on server names, server groups, networks, etc.

We started developing an open-source project called hotwire to address this...

• Inventory System (Servers, Networks, etc)
• Server Builds - RHEL Kickstart, SuSE AutoYaST, (TODO: Debian Preseed, Solaris Jumpstart)

By combining the inventory system with the build system, we've ensures that what is in the database is consistent with what's in our data centers, because we now have to enter the data into the inventory first in order to be able to build the servers.

A client program (funcwire) is then installed on all servers (as part of the build process) which then dynamically keeps an eye on the server hardware as reported by python-dmidecode, and what's in the inventory, so if anything changes, the admins will know immediately.

We've then integrated our wiki system so that each server, rack, project, hardware model etc in hotwire links directly to the appropriate wiki page.

We've hence "documented" our servers/network/etc using hotwire + a wiki (we use confluence here, but any decent wiki will do). (Note however that once the servers are built - hotwire does not modify them in any way - ongoing management is done via cfengine).

Answer 5

I use MikroTik Dude to map things out automatically, this is an awesome application considering it is free. It can also monitor current status. Dude Webpage

Answer 6

The most effective and thorough way to start this process is to build it from a disaster recovery scenario - e.g. the building went up in flames and all we have are the offsite backups. What will we need to buy first, and how will it need to be configured?

Kyle already gave great details, but I find that the DR approach helps me to take things one piece at a time.

Answer 7

Generally you have a few different levels of detail similar to abstractions in software design documentation. You also document general device practices/procedures/configuration. Administrative passwords as applicable.

In an ideal situation, almost everything the next person may need is easily accessible and documented between your guideline and procedure documents + network layout diagrams.

The guideline and procedure documents should, in my opinion, be centralized wherever all of the IT docs are, and the network diagrams may have their own folder structure for multiple locations.

In the case of many satellite sites like a walmart/targer/home depot you would have a generic document for all the branch offices, and then some detailed whole corporation documents of main office interconnections and then you could dive down into office LAN documents.

Answer 8

Approach documenting a network as a developer approaches developing a system...

• Consider the requirements - this has been well noted above, but consider WHO is going to consult the doc-o and for WHAT PURPOSE. Auditors will look for and read different artifacts than a peer SysAdmin.

• Doing doc maintenance - many folks have mentioned the value of diagrams and maps, and as a visual thinker I heartily agree. BUT those things can be invalidated with a single act of adding/removing a host. Think about the 'right level' of doc-o - one that your group can actually maintain.

• Date everything and include notes as to WHY you configured the network the way you did. Many, many folks forget to include a date - but the DATE provides a pointer into the history of the network. Invaluable for problem solving and it mitigates the inherent out-of-dateness of most network diagrams.

• Offload documentation into "processes" - many times solid and well-crafted build/deployment procedures end up streamlining "network documentation" because the details of machine configuration and naming are better described in the procedures.

Key Takeaway: approach documentation as a 'system'; it must provide value from day 1 and it carries with it an inherent responsibility to maintain it.

Answer 9

For some more tutorials on how/what to document, there's networkdocumentation.com.

For some good examples, see ratemynetworkdiagram.com. e.g. This one is pretty good, and this one is awesome ;).

Answer 10

Kyle Noland and other posters have covered a great deal on how to document. We are working on creating a standard web-based software(hosted internally by you) that makes it easier for network and system administrators to document their network.

We have following aspects covered in the software as of this writing(Apr 2012):

• Data Center Documentation.
• Device details (including HW/OS details)
• IP Address management
• Application dependency mapping
• Device relationships - from buildings to virtuals/blades.

You can read more here and we would appreciate your feedback.

Answer 11

At our site, we use several systems to document our own and customer networks. We tried and failed with a lot of techniques/tools wich didn't scale, but now we are quite set with the following:

• DokuWiki for tips, detailed descriptions of configurations and
• Tables (Patchport/MAC/IP/Hostname/Role/Admin-Lookup for all devices, Networks/VLANs/VPNs, Hardware overview, etc)
• RSS to spread changes of wiki pages
• Visio (best company M$ ever bought...) to draw diagrams of everything
• KeePass for Passwords, including logins for vendor ticket systems
• RackTables to document where the devices are located and patched
• Ticket System, accessable for customers
• WhatsUp Gold and other tools for monitoring and reporting
• Mailing lists to keep people up to date

If one deals with lots of IP networks, phpIP could be a suitable IPAM solution.

Answer 12

It usually isn't documented, but if you are being kind, you usually do it in a program like Visio or an open source equivalent. The most important information is what equipment is connected to what, and the passwords for any management console. The rest can usually be divined.

Answer 13

In my previous career as an IT Manager, my documentation binder included a Visio diagram of all the devices, a list of the IP address range allocations, all the product keys for Windows/Office/Acrobat, instructions on what needs to be installed on new computers with step-by-step instructions how, complete hardware inventory down to the component level, and last but not least the emergency phone number list: ISP tech support, router manufacturer tech support, etc.

Answer 14

I use tools like Microsoft Visio or WhatsUp Gold to map out the network topology if that helps.

Answer 15

As mentioned, it depends on a number of factors...

My goal was to have sufficient documentation that I could (conceptually, at least) hand it all to a co-worker and say "see you in 3 weeks," and know that all the important details were there.

• Passwords for all servers and devices (switches, printers, etc.)
• Passwords for any registration-required sites - ISP, domain name registration, hardware warranties, certificate authorities, etc.
• Map of IP addresses used - internal, external, dmz, blocks of DHCP, etc.
• Details of each server: standard stuff like serial number, amount of disk, ram, etc., but we also kept a running log of everything that was done to the box, starting with setup notes (o/s and app. install), then ll configuration and subsequent changes.

I never managed to do it completely, but I aimed to document all major routine processes - how servers were set up, how and what was monitored, account setup and removal, backup, etc.

Answer 16

Map and document your network may be a good way to transfer the necessary information. MS Visio is a diagram tool, but it is static and you have to spend a lot of time on it. I found NetBrain is an ideal network diagram tool to do this. It can document the network instantly and the documentation can be export to Visio or Word. I can customize the contents that I want while documenting my network. The customized contents include: 

1. Inventory-related contents such as Serial number, OS version etc 
2. Design-related contents such as dynamic routing, QoS, Traffic filtering 
3. Traffic path related contents… 
4. Configuration file related contents 
5. Diagram

You can try to document your network on the website.

Answer 17

I'll suggest http://opennetadmin.com. It does many of the things people have suggested in other comments.

Answer 18

MS Visio is a good way to document a network, but it's not a free solution. Gliffy is a nice product if you're looking to keep your costs low.

Typical network diagrams show how information flows through your devices (and usually out to the Internet). So, you should have information in your diagram about where your computers, printers, WAPs, IP phones (if applicable), switches, and routers are located and how they are connected. IP addresses may also be included with the name of your device. This is helpful if you want to glance at your diagram for information on the fly.

Answer 19

NodeSystems is exactly that - a Network Documentation tool. As a nice side effect, it will create an interactive diagram for you.

Check out the online demo: http://www.nodesystems.org/demo/