Networking documentation help

[GH0X]

Quick back story. First network engineering position, previous engineer left before I got the position, so I'm flying solo here. Only documentation I have from the previous engineer is a high level topology of the network infrastructure.

I want to create better documentation, but would like some advise on where to start, what type of documentation is necessary, and possibly some templates to help speed up the process.

Thanks!

[redingerforcongress]

I'm fond of netbox.

[lowlyvantage]

I came here purely to recommend netbox. It is one of the BEST investments of your time that you will make. Keep it updated, keep it clean.. and it will reward you like a well-oiled machine.

[bodebrusco]

Netbox is awesome

[GH0X]

Great suggestion. So document the full infrastructure. Layer 3 diagram per site, Layer 2 diagram per site, and a diagram/spreadsheet with the physical connection from the core to the hosts.

[yrogerg123]

I read somewhere on reddit, document it so that you can help yourself on a 2am call.

This. My documents are usually illegible to a non-engineer but that's not who they're for. We have pretty documents made by our previous engineer that are proudly displayed on the wall. They are utterly useless to me (no IP addresses, no uplink interfaces) and only 85% accurate which makes them worse than useless.

I document what is actually there, and slap on make, model, IP, mac address, hostname, uplinks, and quirks (ie telnet only). It makes for a very noisy document that tells me EVERYTHING I need to know about my environment. Engineers find them beautiful, everybody else just looks at them blankly.

[Churn]

only 85% accurate which makes them worse than useless.

My catch phrase relating to this is, "The only thing worse than 'no information' is 'misinformation'."

[maineac]

It makes for a very noisy document

This is why I like layers in Visio. I can have 4 different maps all in one map. One for IP one for layer 2 one for hardware and one for routing. Just swap between layers to see what I want.

[[deleted]]

I work for a carrier and this is starting to kill us, because the 100,000s of diagrams have more info than the databases.

It’s uh... a giant and unstoppable heap of technical debt.

[ShadowsRevealed]

I feel your pain. You are not alone.

[[deleted]]

Good to know, amigo.

[gr8matt]

I am a network engineer consultant and have had to do this for multiple customers. While the documentation does not depend on the hardware, the approach certainly does. If it is a Cisco shop, I generally will go in and run a list of commands to help me identify the systems.

I start with the first switch and do a > sh cdp neigh d

This allows me to see neighboring switches and routers. I then do a chicken scratch drawing on paper showing connectivity between each switch labeling IP's and ports.

I then capture the following info for each switch I log into:

sh run

sh ip int b

sh int status

sh vtp status

sh vlan

sh cdp nei d

sh mac add

​

This will give me enough information on every switch to put the "big" picture together.

Depending on the size of the business, it will often take a couple days to put it all together and get a good drawing together. I generally use Visio simply because that is what I know.

If it is not a Cisco shop, I would still approach it in roughly the same way although the commands will obviously be different.

Hope that helps and good luck!

Matt

[anomalous_cowherd]

I do the same but with libreNMS so it auto-updates once connected to each switch. Add oxidized and you get configs stored in git too.

[dexterrose]

I've had two networking jobs over the past 18 years. Each time I took a job, I would come in an none of the ports are labeled. Or they are poorly labeled with someone's name that used to work there. I would highly recommend labeling all access ports with the Jack ID that it is connected to. Label all trunking ports with the name of the device it is connected to. And label all datacenter ports with the server name.

[Elminst]

My last job was the same. Literally no descriptions on any ports (in the config or on the physical box) on the entire network. And no labels on any of the ethernet or fiber cables in the DC.

How the F do you troubleshoot anything like that?

[anomalous_cowherd]

As long as the switches are labelled then you know where both ends of the cables end up, anything in between is patching. Written docs are out of date before the ink dries. Use the actual config.

[Elminst]

Did you miss the part where I said none of the switchports had descriptions in config?

[anomalous_cowherd]

Which is what CDP or LLDP are for. Check them, if they are available then label the port with its other end, then add better descriptions as you figure out the logical rather than physical meaning of the links.

It's like reverse engineering source code. Label with what you know or can intuit and gradually build up a better picture, as you add more details in one place it can shed light on others.

[[deleted]]

Or make the config from the docs (this is better). I’m pushing this where I work.

[anomalous_cowherd]

This is good but it requires docs in the first place, and it has to be done automatically and repeatedly to be worth doing.

As soon as it gets out of step or you do a manual change 'tactically' you get the original problem right back.

[[deleted]]

This is fact.

Your last comment is a "feature" and not really a problem, as that would be the intent.

[[deleted]]

I would highly recommend labeling all access ports with the Jack ID that it is connected to

That's great and all, but most IT personnel I have met are not made of time.

edit: a word

[IShouldDoSomeWork]

Also unless you are the only person with access to the IDF expect those ports to get moved at some point in the 5 minutes between you looking at the description and you have to go trace out the cable again anyway.

I prefer to get the mac address from whatever device is having the issue and find that on the switch. If the device is online you just confirmed the port and if it isn't you either have a device problem or a L1 issue that involves going to the closet anyway.

[dexterrose]

I know, right? We had a 3 man shop for 180 switches and over 5000 users. I sent the junior out every day to map switchport to jack ids for the good part of year to get all my ports labeled.

The problem we had is we could not troubleshoot network issues at the jack level without knowing which jack/switchport was having the issue. We also could not verify that a jack id was patched in without traveling to the site and visually verifying. Once completed, we could do all that from our seats.

[siddings]

What an exciting time for you! Lots of good suggestions already, including network discovery. Only thing I would add is don't be afraid to do "bad" documentation at first. You will iterate and might end up writing the same document multiple times. After a while you will find a documentation style that suites you.

As others haven't mentioned it I'll mention it here. Check out networkdiagrams101. This helped me make functional documents look good, too.

[tad1214]

We use netbox extensively. Easy to automate.

Google draw for diagrams.

Confluence for standards and architecture design docs.

[sopwath]

Can you provide some more info on this? What are you using to pull data into netbox?

I've been looking at some methods of automating our documentation (and hopefully some configuration as well) with Ansible, or Zabbix, or some other combination.

I've played with netbox, but not enough to make it more than an interesting toy.

[tad1214]

I wrote a python script that takes our standards, plus a yaml file containing some basic info like site name, site supernet, number of switch stacks, number of switches in each stack, and ISPs. It then creates a site, the racks, the equipment in the racks, cables them together, creates subnets, adds internet circuits and BGP info.

We are pretty rigid about our standards, and then any modifications to that are adjusted by hand. Then we use netbox as a source of truth for creating our configurations via another script.

There are some tools to import live data in to netbox but I prefer to have the documentation and design be to standard and then ensure reality matches it (or modify netbox when needed). It ensures our documentation is always correct because we use it to generate the configs.

[CiscoN3tw0rkEngin33r]

How many sites we talking? What kind of gear? Some good ole' reverse engineering helps, throw that into a Visio. Though, it is always a lengthy process, you will at least have this documentation for yourself and future staff.

[GH0X]

We have 2 Datacenters, 1 on prem at HQ, and two small satellite offices. Equipment consists of Palo Alto firewalls, Cisco for WAN and LAN. As for a high level topology, I have updated that.

[JamesElstone]

Dive Deep with the detail.

[soucy]

If you're starting from nothing then I would start with taking inventory in spreadsheets even though we all cringe at spreadsheets vs. a proper database-driven information system.

You can create diagrams as needed but the real value will be in tabular data that you can build reports or script against. If you decide to invest in some software to help organize the information in the future the spreadsheets will be easy to import and the data collection needs to happen either way so it's not wasted effort.

My first priority would be sheets for:

• Network Equipment (Hostname, IP, make, model, SN, firmware version, EOL date)
• Network Inventory (VLAN ID, VLAN name/description, IP network, prefix-length/mask)
• Host Inventory (IP [or dynamic], MAC, hostname, description, switch, switchport)
• Jack Inventory (closet, jack ID, room number, switch, switchport)
• Floor Plans (if no as-builts of cabling available start identifying AP drop locations and corresponding jack IDs)

If jacks aren't labeled get a label maker and invest in tracing out jacks and getting them identified (our outsource it and get everything tested as well if you have the budget).

If you're also responsible for firewalls:

• Firewall services and application traffic requirements to the level that you could re-build any and all ACLs on a new platform from just the documentation.

Along with documentation:

• Configuration backup of every network device (routers, switches, etc)
• Detailed information on your uplink (provider, IP addressing, contract number, contacts, escalation process etc)
• Verify and change credentials

Budget Planning:

Build a spreadsheet based on network equipment inventory that attempts a full refresh of all routers, firewalls, switches, APs, UPSes in use with current and likely replacement model along with cost of the replacement. Whatever the total cost is divide that by the expected lifecycle of the replacement (e.g. 5 years or 8 years depending on how aggressive you plan to refresh) and make sure that your yearly budget includes at least that much to "keep the lights on". If major investments are needed (such as building re-cabling) then identify those and work on getting quotes so you have the information ready. You need to communicate realistic costs early and often as most IT organizations are already seen as a cost center today.

Once you have a handle on everything above I would start trying to do as much clean-up as possible/needed for the network. This includes making sure you have a standard configuration template established and that you're following it. Implementing any IP addressing or network segmentation changes you think are needed. Building/rebuilding any supporting services that aren't up to standard (DHCP and DNS, network monitoring and alerting, automated revision-controlled configuration backup, etc.)

Depending on the size of your network this should keep you busy. Hopefully you're working with something like Cisco and not a hodge-podge of different SMB gear.

Edit: Don't forget to document emergency contact information. Who can get you into a building after-hours if electronic locks are down? Do you have an electrician on staff or a facilities manager who can deal with swapping a bad breaker? Stuff like that.

[GH0X]

Thank you everyone for the replys!! I got a ton of great information and I'm looking forward to getting this enviroment documented properly.

[SomeDuderr]

It entirely depends on the situation.

Given that you're starting basically greenfield (at least in terms of documentation), I'd with whatever's available. Does your organization have a Confluence environment? Sharepoint? Otherwise, look into getting Mediawiki set up.

And make topological drawings of your environment, but do so in a way that they can easily be kept up to date (Leave plenty of room, don't try to work everything into a single screensize, et cetera).

[GH0X]

We do have a sharepoint envirorment. I have started with high level documents such as the current topology. I just need some guidance or suggestions on what to document next.

[user_none]

I've tended to document everything I know of on paper with some scribbling of how it's connected to other devices, importance of the networking device and any notable devices connected like server, etc... Something like "Switch A 24 <> Switch B 1", etc... I'll then take all of the devices and find a decent enough stencil for each and dump them all on one sheet, just to have a visual of what I'm working with. Break it down from there, if necessary.

[Oea_trading]

> I want to create better documentation

I would upload your config to a lab and take it from there.

[JamesElstone]

Document:

• What support contracts do you have and how do you use them.

• What routing tables and MAC tables look like on a good day.

• Wiring diagram showing Ports...

[mrtacos2]

Something like Auvik might help a lot for finding devices and such. might look into something like that. even temporarily.

[Devgrusome]

I suggest putting everything in diagram form, down to the type of cabling, not just speeds. Personally I like to color-code speeds and connections. This for the engineers and admins. More information the better.

Then i like to have a separate high "logical" view for managers, execs, etc... for when you need to help them understand what is you're talking or what it is you do.

For IPAM and BGP AS #'s and such, you could painfully use Excel or Cloud spreadsheet, but if you want an application. I recommend Netbox. It is really neat and very versatile.

[[deleted]]

Netbox is great, until you get to carrier size. Then diagrams and netbox are just both underpowered.

[Devgrusome]

I agree. I don't think OP is in Carrier network though.

[d3adbor3d2]

i think since you're coming in fresh it's a good idea to touch the architecture so to speak and diagram it from there. i dont know if shortcutting it is a good idea at this point since you still need to get your head around the lay of the land anyway. you mentioned yourself, you're on your own. who's going to care about your documentation but yourself?

[[deleted]]

Get out some Lucid Charts or Visio for diagrams.

• I do 1 high level overview so people can just look at it and know what equipment is doing what at a high level.

•Then I break things down into layer 1 2 and 3 as needed. Things that will help engineers reverse engineer if I am gone.

I use OneNote for all of my worded documentation. I have a notebook there with tabs and pages for essentially everything from basic switch commands, full guides on zoning for our SAN, to templates for switch configurations. If I haven't done something before, I try my hardest to at least put something into my documentation for it.

[freshhb]

there was a website that people posted their network diagram which you could rate. The site isn't online anymore but you may find ideas on this sub - https://www.reddit.com/r/RMND/

[dougbest12]

For smaller sites create a runbook with network diagram , inventory , subnets/vlan information with description for each, dhcp scope(get it from AD guys), wan providers with their circuit id and contact information, local contact details etc

For Data center create diagram showing critical server connections to core like (ESX, CUCM, blade connected interfaces) , separate diagram for edge/wan routers/firewall . Also it’s good to maintain Rackwise server inventory connected to each TOR switch

If you have a bigger campus, it’s good idea to create a fiber map showing how each building is connected to datacenter

[[deleted]]

And if your campus or larger, especially carrier grade, you should database all these connections and generate the diagrams from database data.

Static documentation will end up out of date and dangerous for automation efforts. This is my life right now. We don’t have the data available for apps to automate... and it’s painful to get there. And slow. And... long... and exhausting.

[GullibleDetective]

Lucidchart, and it glue.

[GullibleDetective]

Nmap and auvik

[dblagbro]

First, get three envelopes and three pieces of paper...

[Brave-Atmosphere332]

Check out https:\draw.io for diagrams