Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Documenting a Network?

kdawson posted more than 5 years ago | from the what-matters dept.

Networking 528

Philip writes "Three years ago I was appointed as a network manager to a barely functioning MS-based network. Since then I've managed to get it up and running — even thriving — but have been guilty of being too busy with the doing of it to document the changes and systems that were put in place. Now as I look back, I'm worried that I am the only one who will ever know how this network works. If I get hit by a bus or throw in the towel for any reason, I'd be leaving behind a network that requires some significant expertise to run. Ultimately, this won't be a good reference for me if they are trying to work out technical details for years to come. It looks like I'm going to have to document the network with all sorts of details that outside consultants could understand too (no, I don't want to be the outside consultant), especially since it's likely that my replacement will have less technical expertise (read 'cheaper'). Are there any good templates out there for documenting networks? Is anyone who has done it before willing to share some experiences? What did you wish your predecessor had written down about a network that you inherited?"

cancel ×

528 comments

Sorry! There are no comments related to the filter you selected.

I know... (5, Funny)

EdIII (1114411) | more than 5 years ago | (#28091439)

What did you wish your predecessor had written down about a network that you inherited?

The Passwords.

Re:I know... (5, Insightful)

Drinking Bleach (975757) | more than 5 years ago | (#28091545)

Whether the comment was intended to be funny, I find this to actually be a serious issue...

Re:I know... (-1, Flamebait)

Anonymous Coward | more than 5 years ago | (#28091657)

I find your mother to be a good fuck.

Re:I know... (1, Funny)

Jurily (900488) | more than 5 years ago | (#28092069)

Whether the comment was intended to be funny, I find this to actually be a serious issue...

If the predecessor does write the passwords down, he deserves to be fired.

Re:I know... (3, Insightful)

stonedcat (80201) | more than 5 years ago | (#28092085)

At which point you won't be getting the passwords anyway since you fired him/her? Good idea. ^_^

Re:I know... (5, Interesting)

2Bits (167227) | more than 5 years ago | (#28091561)

This may sound funny, but I recently had the same experience. I took over the position of CTO of an electronic payment company, and after one week, I figured a lot of critical systems are missing root password, including Linux, AIX, HP/UX and SCO Unixware. No one knows the password, it's been changing hands so many times, and the people who were responsible for those machines have left, without leaving the passwords behind.

Those are critical systems that must run 24x7. We had to rebuild the system on new machines, re-route transactions to the new machines, and shutdown the old ones to recover (single user mode).

And that's a platform handling over 400 billion in transaction per year. Scary. But that's the easiest problem I have inherited, mind you.

Re:I know... (1)

hasdikarlsam (414514) | more than 5 years ago | (#28091811)

Hang on, didn't they have replicas? Fault-tolerance?

I'd expect a system that important to survive the temporary loss of any single computer

Re:I know... (2, Interesting)

Architect_sasyr (938685) | more than 5 years ago | (#28091887)

I note that GP was very careful to mention "systems" as a plural a lot. There is a cluster near me at the moment which nobody knows the root password to (until a recent local kernel root exploit at least) because of a very similar situation. Thankfully we got them back with a lot less trouble than this one, but there it is.

Re:I know... (4, Funny)

Anonymous Coward | more than 5 years ago | (#28091895)

So that's what happened during the bank collapse!

Re:I know... (0)

Anonymous Coward | more than 5 years ago | (#28091993)

Erm, you have 24x7 critical systems running on *single* hardware boxes?
Now that is scary. Also a nice way to rip off customers (who probably believe they're paying for a real HA-solution)

And yes, losing passwords or having undocumented systems really seems to be the easiest problem you inherited.

Good luck (I hope you can sleep at nights!).

Re:I know... (1, Funny)

Anonymous Coward | more than 5 years ago | (#28092015)

I only wish the chief technician told me where my predecessor had hidden the note with the passwords.

Do what the guy before me did (5, Funny)

TornCityVenz (1123185) | more than 5 years ago | (#28091447)

Use Post-its.

Re:Do what the guy before me did (4, Insightful)

FooAtWFU (699187) | more than 5 years ago | (#28091489)

The nice thing about post-its is that they can be updated very easily when you're fiddling with the device. That doesn't work if you're configuring it remotely, though. :|

The next step up from a Post-It, though, is a snazzy label-maker. My portion of the company uses these extensively to document our development lab (we do some NMSy stuff). Of course, it's not a production network, and standards are a little different.

Department of Redundancy Department (0, Flamebait)

Anonymous Coward | more than 5 years ago | (#28091453)

a barely functioning MS-based network

That's completely redundant. If it's not the shitty network stack back in the day, it's the malware-ridden security nightmare of the present. Either way, there's no need to waste so many words.

Re:Department of Redundancy Department (5, Funny)

binarylarry (1338699) | more than 5 years ago | (#28091675)

Now I see this Microsoft bashing on Slashdot regularly and it's completely unfounded. I use a Windows-based PC and it has provided me with years of worry, virus and spyware free operation.

In fact, our PC's at work are WeOffer popular brand names drugs such as ViagraFrom $1.87, CialiFrom $2.38, SomaFrom $1.07, TramadolFrom $1.38, LevitrvFrom $2.52, Celebre, Zocor, Fosamax, Effexor, Zyrtec, Plavix, Premarin, Flomax, Paxil, Zoloft, Prevacid, and Evista. Now it's easy to get your needed drugs 0nline.
   

Re:Department of Redundancy Department (1)

MichaelSmith (789609) | more than 5 years ago | (#28091711)

At home I have an inbox which gets ~200 spams a day at the moment. 1000 at the peak. Every day I browse the Sender field just in case it contains a legit message, then I delete the lot. Last night I noticed an email from an old friend who I hadn't heard from for three of four years. I opened the message and sure enough it was spam. I am pretty sure it came from her PC. My old address must still be in her address book.

Windows != SPAM (4, Insightful)

nuckfuts (690967) | more than 5 years ago | (#28092035)

Attempting (even facetiously) to blame SPAM on Windows is wrong. If every copy of Windows on the Internet somehow magically disappeared, the SPAM problem would not abate. Bot herders and spammers would simply shift their efforts to other platforms.

If your doubt this, consider what the winner of this year's PWN2OWN [tippingpoint.com] contest had to say about why it's easier to target Mac OS X [zdnet.com] .

BTW, this is not a troll, and I'm not a (Windows|Mac|Linux) evangelist of any kind. I just find kneejerk Windows bashing rather tiresome

Good News (5, Interesting)

N3Roaster (888781) | more than 5 years ago | (#28091473)

Your successor will never find any documentation that you leave behind (or if you show it to them they won't bother with reading it) and by the time they notice it they'll have already screwed things up to the point where the documentation will be obsolete. This means you can save yourself the trouble of doing the documentation unless that documentation is going to make you more effective while you're there.

Better News (0)

Anonymous Coward | more than 5 years ago | (#28091559)

This means you have some pretty good job security, wouldn't it?

Re:Better News (5, Insightful)

binarylarry (1338699) | more than 5 years ago | (#28091695)

Not really, because as most high level executives know, IT doesn't really do anything!

Re:Better News (3, Funny)

Anonymous Coward | more than 5 years ago | (#28091763)

When I was part of an IBM sales team in The Old Days we used to scare prospects by asking to see their network diagram. Almost never appeared.
Then we'd ask who owned the network. That was good for laughs.
Finally we'd ask why the most important part of the network (the end user) didn't appear on the diagram (assuming they could produce one).
By the looks of it nothing's changed.

Re:Better News (1)

Achromatic1978 (916097) | more than 5 years ago | (#28091911)

When I was part of an IBM sales team in The Old Days ... Finally we'd ask why the most important part of the network (the end user)

I call BS. The most important part of the network to an IBM sales team was a small army of consultants, racking up hundreds, if not thousands of billable hours, whilst a PM or Sales Manager held the customer by the balls.

Re:Good News (5, Insightful)

BrokenHalo (565198) | more than 5 years ago | (#28091715)

...or if you show it to them they won't bother with reading it

This is more to the point. Most network admins have the attention span of a flea and won't read past the first sentence of anything you write; actually, I could probably expand that statement to include most people generally. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Re:Good News (5, Funny)

MaskedSlacker (911878) | more than 5 years ago | (#28091785)

You just thought I wouldn't catch a reference to Cicero's De Finibus Bonorum et Malorum.

Original Lation from which it was derived: ...neque porro quisquam est, qui dolorem ipsum, quia dolor sit amet, consectetur, adipisci[ng] velit, sed quia non numquam eius modi tempora incidunt, ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit, qui in ea voluptate velit esse, quam nihil molestiae consequatur, vel illum, qui dolorem eum fugiat, quo voluptas nulla pariatur?
        At vero eos et accusamus et iusto odio dignissimos ducimus, qui blanditiis praesentium voluptatum deleniti atque corrupti, quos dolores et quas molestias excepturi sint, obcaecati cupiditate non provident, similique sunt in culpa, qui officia deserunt mollitia animi, id est laborum et dolorum fuga.

English:

        Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but because occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences, or one who avoids a pain that produces no resultant pleasure?
        On the other hand, we denounce with righteous indignation and dislike men who are so beguiled and demoralized by the charms of pleasure of the moment, so blinded by desire, that they cannot foresee the pain and trouble that are bound to ensue; and equal blame belongs to those who fail in their duty through weakness of will, which is the same as saying through shrinking from toil and pain.

What was that about my attention span?

Re:Good News (1)

Guruthegreat (971683) | more than 5 years ago | (#28091803)

Non Sequitor, I fail to see the relevance of love, pain, and pleasure on the attention span of the average sysadmin.

Re:Good News (1)

hasdikarlsam (414514) | more than 5 years ago | (#28091829)

Love destroys it, the promise of pleasure or pain can improve it.

Re:Good News (5, Funny)

Tiger4 (840741) | more than 5 years ago | (#28091933)

...fellatio uber alles...

WTF???

Re:Good News (1)

masdog (794316) | more than 5 years ago | (#28091843)

This may seem like a joke, but it is exactly what happened when I left my last job.

N3Roaster: who are you? (1)

jotaeleemeese (303437) | more than 5 years ago | (#28091859)

Please, tell me your real name, I don't want to have you anywhere close to my systems as soon as I don't get a pension cheque.

Re:N3Roaster: who are you? (1, Offtopic)

N3Roaster (888781) | more than 5 years ago | (#28091919)

It's very easy to find my real name (you could start with my homepage link and read the first page of any linked PDF [amusingly enough, those would be source code documentation that is considerably more extensive than is normal for software but having it makes me far more productive] or you could go to my journal, find out that I have the same user name on Twitter and get it there), but you really don't have to worry about me getting anywhere near your systems. For what it's worth, I was going for Funny/Troll. I have no idea how I ended up getting that Interesting mod.

get some help (5, Insightful)

Jean-Luc Picard (1525351) | more than 5 years ago | (#28091481)

Sounds like a very easy way to over work and over stress your self, get some help one way or another. Summer is coming and I'm sure there are plenty of Comp Sci/Network Engineer/IT students that could of help. It may not be a bad idea if you make a plan of some kind before you go head in.

Re:get some help (1)

node159 (636992) | more than 5 years ago | (#28091687)

I concur, nothing like showing a fresh grad the realities of IT by making him document a network without assistance.

On another note, if you ever expect some form of job mobility or flexibility, theres nothing like saying 'heres the documentation, cya'.

Just go ahead and quit already (0, Informative)

Anonymous Coward | more than 5 years ago | (#28091485)

It's really not as complex of a network as you may think. Go ahead and quit - the sun will still rise and the email will still be delivered....

Documenting teamwork (3, Interesting)

Anonymous Coward | more than 5 years ago | (#28091491)

1. Simply begin documenting, its a work in progress..never finished. 2. Select a worthy staff member from your org, with the brain cells (and desire)to start learning networking, and begin to train him/her on what you are documenting. 2.a refrain from selecting the network thinks-he-knows-it-all type, instead pick anyone else with the skills listed in 2.

Alternatively... (2, Interesting)

Anonymous Coward | more than 5 years ago | (#28091499)

Professionalism be damned, we're in the middle of a recession and you're wanting to make yourself dispensable? Go ahead by all means, but pass your boss my number :)

Re:Alternatively... (0, Redundant)

Anonymous Coward | more than 5 years ago | (#28091613)

Dispensable, or actually able to take a vacation?

Re:Alternatively... (4, Funny)

cyber-dragon.net (899244) | more than 5 years ago | (#28091705)

English only please... I don't understand this word "vacation" you have mixed in with the others.

Re:Alternatively... (0, Redundant)

darth dickinson (169021) | more than 5 years ago | (#28091717)

Parent is redundant.

Re:Alternatively... (0)

Anonymous Coward | more than 5 years ago | (#28091891)

Redundant statement is redundant

What about? (4, Informative)

DaMattster (977781) | more than 5 years ago | (#28091507)

A good tool like dia which can allow you to create a network diagram. When it comes to documenting a network, a picture can be worth a thousand words. Or you could also use MS Visio as it is, perish the thought, a good tool. A good, detailed diagram can come in very handy as a reference tool for your own use in case of a failure.

Re:What about? (0)

Anonymous Coward | more than 5 years ago | (#28091537)

A good tool like dia which can allow you to create a network diagram...

Sure, if he has nothing but time. I'm thinking a screenshot of etherape...

Re:What about? (2, Informative)

drachenstern (160456) | more than 5 years ago | (#28091639)

In other words, the tool you recommend is Etherape?

Any other tools you would use to grab a snapshot?

@the submitter, what about a tool like spiceworks?

Re:What about? (2, Informative)

operator_error (1363139) | more than 5 years ago | (#28091721)

Etherape is gorgeous. I wish I had time to understand what it all means, but still I love firing it up and staring at the network traffic.

Another tool that I've enjoyed much more personal success with is cheops-ng. For documenting a networking, cheops-ng and a decent icon collection provides a pretty snazzy view of what NMAP can see. (NMAP being another tool I haven't had time to fully grok, yet)

http://cheops-ng.sourceforge.net/screenshots.php [sourceforge.net]

Re:What about? (4, Insightful)

RiotingPacifist (1228016) | more than 5 years ago | (#28091871)

A summary diagram (dia/visio) is still pretty key, but nmap (or specifically the latest versions of zenmap (the gui frontent to nmap) provides a good detailed view of network topology and if you include the capture file, you can annotate specific computer details in the notes section (ofc you have to assume your replacement will be familiar with zenmap for that to be useful though)

schematics (5, Informative)

ClaytonianG (512706) | more than 5 years ago | (#28091513)

Basic network documentation:

I've found that starting out with the very basic physical layout and working your way up in complexity is greatly beneficial.

i.e. start out documenting network cable runs including cable type. follow it by switch layout. follow that by routers and vlan setups. follow that by the servers that provide basic network functionality(e.g. DHCP, etc...). If this is a windows network, that would likely mean detailing the domain controller setups. From their systematically document the systems in order of importance to the business, etc...

Also, visual diagrams are extremely helpful.

Re:schematics (1)

DragonDru (984185) | more than 5 years ago | (#28091609)

I second that.
The more you document, and the more places you put that documentation, the better.

Let's be real (5, Interesting)

mcrbids (148650) | more than 5 years ago | (#28091515)

Short answer: don't worry about it too much. Put together enough that it looks like you've done something then go have a beer.

You could have the most amazing docs the world has ever known - with passwords and clear instructions - ad the odds are about 20% that the next guy will even read them.

The next guy will figure that he/she knows much more than you as evidenced by the fact that they are there and you are not. And, the cheaper they are (read: inexperienced) the more likely this is to be the case. When things go wrong, they will blame you anyway.

So document away, but for YOUR sake so that if/when you are called in after the new guy horkens everything, you can have an easy time putting it all back together. But don't wait for the call... people will put up with almost anything when pride is on the line.

And go have a beer.

That is not real, is cynical and unprofessional. (5, Insightful)

jotaeleemeese (303437) | more than 5 years ago | (#28091899)

No wonder our field and many of our professions have such a bad reputation.

I have read only a few posts and two (moded up 5) say pretty much to ignore the issue.

In several networks I have worked with fundamental information was non existent. This translated in lost time, down time and actually losing money (if you lost your job in one of those companies recently, the indolent SAs or Network administrators may be partly to blame).

You never know who the next guy will be, if he is less experienced or capable then the documentation will be very valuable, if he is more experienced or capable then you would have saved their time to do some real work, after all they (and you) have not being hired to do forensics.

How a professional can hide behind the "let's be real" nonsense is beyond the pale.

Start with disaster scenarios (5, Informative)

bjcopeland (70793) | more than 5 years ago | (#28091517)

For me, visio's are great and everything, passwords too, but really the most valuable thing you can do is document single points of failure, outdated software/hardware, etc., license keys/expiration dates, cert expiration dates, personal support contacts you have and all vendor relationship details as well are essential. Do you use change control? If you do, go back and comment your changes, if not, do the best you can at explaining why things are the way they are. Get some open source software that is good at indexing data and create a searchable knowledge base from the information above. Don't concentrate on docs that can be found on the web at first because any admin worth their salt will know where to look for how to's, etc. Focus on the why's, the where's and disaster recovery.

My two cents...

Re:Start with disaster scenarios (3, Informative)

enoz (1181117) | more than 5 years ago | (#28091549)

Get some open source software that is good at indexing data and create a searchable knowledge base from the information above.

A Wiki?

Re:Start with disaster scenarios (1)

bjcopeland (70793) | more than 5 years ago | (#28091591)

Wiki's work, but I am thinking more along the lines of Lucene [apache.org] where you can point it at existing data without much effort. Assuming config changes, cert and license data and network diagrams have usable text already associated with them, you can save a great deal of time just indexing what you have.

Here is what I would get (5, Informative)

Anonymous Coward | more than 5 years ago | (#28091525)

1. Viseo overview of the network drawing with complex areas drawn out specific detailed viseo's (even a scanned sketch or paint drawing is better than nothing)
2. A spreadsheet with circuit ID's mapped to router and interfaces.
3. Document the trunk interfaces as well as the LAG's (Link Agrregation Groups, port channels, whatever you want to call it)
4. TACACS passwords / domain logins in a secure location (or radius or diameter or whatever you use)
5. Data center capacity as a function of 1. Rack Space, Cooling Capacity, Electrical Load.
6. Write brief knowledge articles describing any problem areas and explaining a history of anything you think would be hard to figure out easily. No need to go hog wild, just re-brand the RCA documentation you have. You do have Root Cause Analysis right?
7. Network protocol hierarchy map. Where are your major redistribution points, what is your routing strategy etc.
8. If you have a voice network document all your DID's, PRI trunks, Gatekeepers, Dial Plan, and any translations you use on h.323 gateways or how MGCP or SIP is configured. If you have a complex call center you should probably pay to have it professionally documented in down to the minute detail.
9. SSID's and BSSID's for any wireless you may have as well as passwords, 802.1x authentication methods, along with linking documentation.
10. Make the documentation part of your CMR process (Change Management Review) and incorporate it into the time allotted for a change.

I know these are just rough ideas and you should get many more ideas from all the smarter people on here than myself, but whatever advice you get I would say you would need to have the documentation update able via subversion, or some document control system and have some kind of review process for it, even if it means getting together over pizza with some of the other groups and asking them about their environment and getting pointers and possibly help on documenting it all. Documentation is a full time effort and IMHO there is no such thing as too much documentation. You would be surprised how good documentation can aid you in problem resolution down the road or aid vendor support in helping you resolve a major outage. The three basic principles of network care are document document document. :)

Cheers,

Anonymous Coward.

Well... (0)

Anonymous Coward | more than 5 years ago | (#28091527)

An overwiew map. Helps me figure out the first steps. Firewalls and routing hints are good to place on the map. Any other equipment is good too.

An IP plan detailing networks, their intended use, DHCP scoops, ant things with static IP on those networks.

Passwords to the equipment. And how to access the equipment if it is something unusual.

Two or three small lines detailing anything special with anything.

TiddlyWiki (5, Informative)

bradley13 (1118935) | more than 5 years ago | (#28091533)

On the side, I manage a small network, and I've also wondered the same sort of thing: if someone else needed to find their way around, where would they start.

A Wiki makes for a really nice way to document things, not least because you can include all sorts of cross references. For example, a list of servers, with links to the services they provide - and a list of services, with links to the servers. But Wiki's normally run on servers, which leaves your successor with a chicken-and-egg problem.

A bit of random surfing turned up TiddlyWiki [tiddlywiki.com] , which is a Wiki in a single HTML file. A really elegant bit of engineering, and very handy for self-contained documentation. Since the entire Wiki is just a single file, it's easy to protect. I wound up with two: one with "public" information describing the general architecture and one with private information (including passwords). The private one you can put on a USB-stick in a safe, hand to your boss, or whatever seems appropriate...

setup a wiki (5, Interesting)

blkwolf (18520) | more than 5 years ago | (#28091539)

At my last few companies and my current one that I work out, one of the first things I do is setup an internal only Wiki server.

Not only does this let me document everything I can about the network but I also try an train my co-workers in using it to document information they feel is important for their job too.

The effectiveness though seems to be related to the level of computer literacy of the user, i.e. my last company the software developers went crazy with it and documented everything they could think of. But other than them or us in the I.T. dept, no one use would hardly touch it at all.

Either way it's still a simple method for your to store notes, diagrams or any information about your network in an easy to find single location that you feel would be important to the company should you leave for any reason.

Re:setup a wiki (0)

Anonymous Coward | more than 5 years ago | (#28092033)

if only my predecessor hadn't 'accidentally' deleted our wiki before he left, my job would be so much easier today! :\

Wiki with graphviz (1)

1s44c (552956) | more than 5 years ago | (#28092083)

Totally agree about the wiki. I use a wiki because it's easy to write and fast to update.

All my network diagrams are done in graphviz in mediawiki which is also easy to write and fast to update once you get used to it.

As a bonus mediawiki keeps every old version of your documentation so you can easily prove what great work you have been doing.

False Info (0, Informative)

Anonymous Coward | more than 5 years ago | (#28091555)

The fact is, you're doing this because "Ultimately, this won't be a good reference for me..."

As you leave, say "The network started bad, and will always be bad. I will sue you if you give a bad reference."

Problem solved.

Re:False Info (3, Insightful)

cyber-dragon.net (899244) | more than 5 years ago | (#28091729)

"The network started horrible, here is how I cleaned it up" is a GOOD reference. I have killer references from two jobs I automated myself out of this way. Each time I got a more interesting more challenging better paying job by doing so.

Why do people make things hard for themselves? (5, Informative)

Anonymous Coward | more than 5 years ago | (#28091565)

Why not use an automated too?

www.open-audit.org

Many documents. (1)

bytesex (112972) | more than 5 years ago | (#28091571)

Unlike software documentation, in a network there is more than one approach, pretty much a function of the amount of people that have to fiddle with the network at any given time. Usually there is physical laying of cables (where are they), box location and naming (labeling and Visio-sheets), peripherals (printers, faxes, phone system), box setup (OS and processes), server process configuration specifics and client requirements. And then there's that (what I think) very important document that describes what you wanted and why you implemented it in this way. It's a lot of writing, that's for sure, but like some other poster said: take a brainy, young intern and create this stuff on the fly.

Re:Many documents. (1)

bytesex (112972) | more than 5 years ago | (#28091623)

Oh, and did I mention procedures, like backups ?

The Basics (0, Interesting)

Anonymous Coward | more than 5 years ago | (#28091573)

Passwords!
Vendor support numbers
Circuit ID's
Customer / Client numbers that support asks for
Links to KB articles that have resolved problems in the past.
When where and what the backup system runs. (You do have a backup right?)

Self-Documenting? (1)

tarsi210 (70325) | more than 5 years ago | (#28091587)

Am I the only one who first thought, "If you have done the network correctly, it should explain itself"? Overly-complex networks take overly-complex documentation and overly-complex people to run and maintain. Mind you, there's a difference between correctly-complex and incorrectly-complex, but at the same time, every level of difficulty you go upwards in the configuration scale you exponentially increase the need for carefully calculated and layed-out systems. Ok, ok...now that I'm thrust back into reality...and given that you aren't likely to rebuild your network (although you might consider some re-work to help the self-explanatory aspect)... High level details, locations of closets, routers, switches, major cable runs, passwords, IPs, big details. All the small things the other person will have to figure out anyway and catalogue in their own mind in their own way, so doing it for them won't help a ton. Give them the tools to do their job properly and you'll be sitting fine.

Re:Self-Documenting? (1)

cyber-dragon.net (899244) | more than 5 years ago | (#28091765)

No matter how self explanatory you THINK it is, the poster is right, documenting is important. I have had to come into several environments as a consultant where admins thought the way you do, and they were inevitably wrong. Hell some of the time despite claiming they knew it like the back of their hand they had to ask another guy to answer my questions.

Conversely when the one hiring consultants I fire and only pay half to any who do not provide full documentation, as the job was only half done, and make it clear in their deliverables I expect this, and the level of it. It took me a lot of years and a lot of frustration with my own and other people's lack of it to develop this attitude, and I think you will find it with anyone who has been in the poster's position.

For any network that services more than a small office environment there are going to be quirks and complexities no matter how "right" you do it. Maybe you separated things onto VLANS for reasons that are not inherently obvious, but if you undo it you weaken security, or break an app etc.

I hope you are the only one. (1)

jotaeleemeese (303437) | more than 5 years ago | (#28091915)

Complex is entirely subjective, and as such what is self explanatory to you may not be to others.

Yet another cavalier approach to doing the job properly, and I am not even half way the comments.

Dispiriting frankly :-(

Contact Numbers (5, Insightful)

DragonDru (984185) | more than 5 years ago | (#28091603)

The phone numbers/emails for points of contact in other departments/companies.
You likely don't run *everything* and the new person needs to know who to contact when the interaction between inside and outside fails.

What I use (1)

thatkid_2002 (1529917) | more than 5 years ago | (#28091631)

The consultancy company I work for uses Novell Teaming and a follows a structure described on the main page as:
"This documentation is based on the Network DNA framework, originally developed by Don Krause. Although this is not longer developed by Don, it provides a good starting foundation for documenting a computer network."

This template has been perfect. If you can find the same template and implement it in [insert your favourite Wiki software here(MoinMoin)] then this should be just fine and cost $0.

Unless you're trying to get promoted... (0)

Anonymous Coward | more than 5 years ago | (#28091641)

...why make yourself obsolete? Irreplaceable people can't be promoted, so that may be a motivation to make yourself replaceable, but otherwise nothing good can come of this.

Use MSWord/Ooo in "Outline" mode & start with (1, Insightful)

Anonymous Coward | more than 5 years ago | (#28091661)

I maintain a largish network with vmware-dominated x86 Linux and Windows platforms.
I started with a live document containing a network diagram and a list of servers - meaning anyone can add to it. I use word - and have it in "outline" mode for easy collapsing..

No Passwords are kept in it (passwords are referred to a documented, password protected area within the IT group folder; a sync'd copy in the DR site and a copy with the DR documentation (just in case)).

The document is replicated to DR for survival when you have to rebuild.

My documentation stated with a network diagram now includes a rack layout and wiring diagram; and have now added details such as DHCP configs (although they change... thus the live document - so don't print it or its out of date).

I've even added underground cable runs (found when they pop the lid of the pit - with photo goodness) where fibre run to pits and the electrical company details to how the generator kicks in - who to contact i the event of a transformer blow etc... just in case I forget in 10 years time!

All IT team and top-level managers know "its in the network documentation" if they need to refer and I'm not there. They add their relevant parts - its a live document afterall.

Of course, you MUST make stipulations that this document should NEVER be released outside of the company - otherwise it will be handed over for tender responses; sales/marketing reports; sales people interested in the network; due dillegence reports; accounting audits and toilet-reading-for-those-who-have-nothing-better-to-do... for some reason managers love to use your hardwork to reduce them having to do hardwork - no matter how detrimental it is to the business!

Anyway - keep it a work in progress... and don't put anything in there that could compromise the company if fallen in the wrong hands (see above)..

Good luck... this job is never finished... but will feel good when you have it up-to-date.

I've been doing this for a while (5, Informative)

carlocius (153486) | more than 5 years ago | (#28091665)

My job requires me to do exactly what you're looking to do but for multiple companies/networks. Then, as soon as I'm done, I usually pack up and go or get hired in and fix the network.

Since I'm writing the Network Overview for managers AND potential future network managers I tend to write mine in the following format:

1) Synopsis of what the network does for the company, what general technologies they use (Windows AD vs *nix OD, thin clients vs Windows boxes, Cisco vs Brand X), and what the LOB software is.

2) Points of contact for the ISP and other providers (anti-spam, anti-virus, hardware, etc). Passwords for various accounts and services.

3) Logical network overview map (visio), containing firewalls, routers, switches, other devices, open/forwarded ports, IPs, what the servers do, what vlans are in place, Quick explainations for why (such as why vlan vs a seperate subnet).

4) Physical map of devices if the complexity of the network calls for it.

5) Software notes, what apps are critical for the business and which systems they rely on.

Then, for my specific job I have to do the following:

6) Licensing issues.

7) Network weaknesses/points of failure.

9) Other rec's.

Do what everyone else does. (5, Insightful)

XDirtypunkX (1290358) | more than 5 years ago | (#28091673)

Draw a horrible diagram in Visio (or similar) of what's connected where without any indication how it actually works!

NeDi (1)

Nonesuch (90847) | more than 5 years ago | (#28091681)

If the network itself (switches and routers) is built on Cisco, there are commercial (SolarWinds) and Freeware (NeDi [www.nedi.ch] ) tools to document the interconnections, VLANs, and configs. Assuming you've left CDP enabled and standardized your SNMP community strings, NeDi does a fine job of documenting a network with minimal effort. I've found switches the network team didn't even realize existed just from using the NeDi discovery mode and adding 'public' to the list of SNMP strings to try.

Easy (2, Funny)

Viree (214760) | more than 5 years ago | (#28091699)

nmap -sS -O 10.0.0.0/8 > handover.txt

Lots of flowcharts! (4, Insightful)

onyxruby (118189) | more than 5 years ago | (#28091739)

Present client I am at I inherited a network of about 15,000 clients that was previously managed my a very incompetent IT department. Started by looking at the existing flowcharts and discovered that almost everything that was documented was wrong... Long story short I have been spending a fair bit of time reverse engineering their production environment so that we could accurately document it. Unfortunately we had come to the conclusion that we can use /nothing/ that the previous administrators left behind for documentation. You don't want someone like me coming in and looking at your documentation and declaring you incompetent, it can cost you your job.

You haven't detailed the size of your organization to know if you will need sign off from other departments or not. If possible try to get sign off so that they have a reference and you can create a standard that can be used to fix things and to ensure your designs don't get trampled by a new admin in another department. You really need to provide more detail on your environment for people to answer you.

I do most work in Visio, starting at 50,000 feet and working my way down. At this level I need to document network topology, server distribution and database server distribution. I work my way down from there using a zoom in style that has served me well for 30 some clients. Depending on the size, complexity and your area of responsibility you may need to flowchart anywhere from a 2-3 levels to potentially dozens of disparate processes. You haven't mentioned much about process development, I assume you want people to know how to do at least critical portions. Never write a process without flowcharting it, this will save you grief by getting people to focus on the process instead of a step by step set of directions. It takes someone fairly good to document the complex and make it look simple, that is your job at this point in time.

The bottom line is that your documentation should show dataflow for each critical system. As long as you can do this someone else can step in and work with what you have, even if they may not understand a given piece. One of the big advantages of flowcharting everything (especially processes!) is that this will readily show you weakness and holes that may have been previously overlooked. When flowcharting complex processes don't be afraid to have a single point represent an entire additional complex process that can be distictly referenced of it's own accord (as an car repair manual of mine once described the process to replace a crankshaft "Step 1. Remove Engine".) If you try to put to much detail in a given process you lose your audience and the value of the documentation.

Bottom line when I am done with a design document it covers server, network, database and client topology in varying levels of detail with dataflow. A typical design document I would turn over would be 150 pages with most of that broken down into different sections describing what was done, why it was done, the best practices followed for build, and best practices for lifecycle. The document typically does not get read by any one person, instead it would be a reference for a number of different departments that will each reference it according to their own needs.

Re:Lots of flowcharts! (0)

Anonymous Coward | more than 5 years ago | (#28091777)

Previously managed??

Re:Lots of flowcharts! (1)

onyxruby (118189) | more than 5 years ago | (#28091793)

The previous administrators are now gone for incompetence and the process of damage control and bringing their environment into best practice has begun.

Re:Lots of flowcharts! (1, Informative)

Anonymous Coward | more than 5 years ago | (#28092091)

Dude, I can brag too. I have managed networks for hundreds of customers, and you know what? A 150 page document is worse than fricken useless. We had idiots who tried to get us to use that kind of documentation. Fortunately, they were laughed out of the office. And you get people 'fired for their incompetency'??? There was a poster up above who had a much more useful checklist with REALISTIC guidelines, who deserved to be modded up.

Like:
  Change management, with documentation requirements
  Network diagrams, both logical and physical. You may not agree with Cisco, but their layered networking model does make documenting networks easier.
      Circuit ids labeled on diagrams (so you can find them when you're troubleshooting)
      Port numbers for important ports like trunks and circuit termination points
      Include the routing protocols, if used
      VLAN or VSAN ids allowed on trunk ports, if used
      Rack space diagrams, so you know WHERE your devices are, and if you have space for more.
  Have a centralized database for passwords
  Keep centralized records for after action or root cause analysis reviews and documentation
  Keep an inventory
      network devices
      critical spares
      circuit ids
  Know
      how much power you need
      how much cooling you need

Now, in all honesty what you provide may be nice for an IT department who has no documentation whatsoever, but for a network admin who's looking to build something useful for himself and for future lackeys? Get real and quit bragging.

Incentive to do this (1)

cjacobs001 (644842) | more than 5 years ago | (#28091761)

after reading most of the 35 'replys' received in the 1/2 hour or so since the article was posted, it seems that most reply-ers may not be familiar with the requirements of 'electronic discovery'. If an entity becomes a participant in a federal law suit (even a non-party participant), and, increasingly in the state courts, a logical inventory of your network is the minimum that must be ready to be shared with the other parties in the suit (basically). [i am not an attorney, nor a spokesperson] I say minimum because the rest of the requirements are a whole lot more detailed; inventories of all network devices and data storage devices, including how each may be used, when it was last reformatted, last replaced, what happened to that replaced storage device, whether or not there is any policy for that, how it may be enforced, etc., all data on any part of your network, how\why it is accumulated, what types of document formats, policies & procedures for the same and including data destruction, all users and their permissions to that data, back-ups, web sites, blogs relative to the entity or where entity-specific information may be located, emails, etc, etc... . . oh, and then there is also the data authentication procedures if you hope to use anything electronically stored in court. And by the way, data in RAM may also be an issue, sometimes!!?? - just some incentive for all of us to work this out.

Sigh (0)

Anonymous Coward | more than 5 years ago | (#28091775)

This is why you document while you do the work.

Use obvious design (2, Insightful)

hugetoon (766694) | more than 5 years ago | (#28091781)

Most equipments systems and application have fancy features that allow to do elaborate things efficiently with less resources. This is an enjoyable part of our work, unfortunately it should be banned.

Restrain Yourself from the temptation to use those features.
Implement everything with the most basic and standard approach.

This may be frustrating, you may feel that you are wasting cash and time and sacrificing performance, but actually you'll get a more reliable and flexible system. And and outsider will be able to understand it more quickly.

Most systems allow to insert comments in the configuration. Use that extensively. The comments are the most immediate documentation and usually the most up to date.

One last hint: once your system is running and you have removed anything fancy from it leaving only the necessary complexity, take 15 minutes to describe the profile of the person that is eligible to manage it. Include books with the general knowledge that this person will need. Handle the description to your management.
This approach has following advantages:
- screening out totally unfit candidates
- helping the successor filling gaps in his knowledge
- avoiding to describe in your documentation common knowledge (in my experience this is 30-70% of the document and could be replaced with references to appropriate books)
- (free bonus) giving the management a better understanding of your own value

There are drawbacks as well:
- Going through books would take more to get a grasp than if you explain everything inline.

You can palliate by giving references to specific chapters. And stress on the fact that no one should be allowed to touch the systems *before* having the knowledge in the book. It's like driving the car: you should learn *before*, not *while* going to the highway.

Simplify before documenting (1, Insightful)

Anonymous Coward | more than 5 years ago | (#28091789)

I work as an architect rather than at the coalface of keeping a network of the kind described going, but one policy I would suggest is that if there are particular aspects of your network you think will be hard to document, it would be profitable to change the truth about those aspects to something you will find easier to describe.
Ideally you should do this by changing the implementation without noticeably affecting the services provided to end-users. Software development people may recognize this as relating to the concept of refactoring.

Cable labels (1)

Masa (74401) | more than 5 years ago | (#28091831)

I only have one tip: label cables clearly at both end.

Documentation at your hands, and timestamped (3, Insightful)

isj (453011) | more than 5 years ago | (#28091837)

If you are in the server room, and you have:
A: a spreadsheet that your predecessor made.
B: a post-it note on the switch saying it what it does.
Which one do you trust?

For the physical/low-level network the documentation should be in the network. Just like source code should contain comments about this particular piece of code, a similar approach works reasonably for the physical network. I see no point in a having an outdated spreadsheet. It is more useful that the cables and ports are labelled and numbered, that there is a post-it note on a switch say where the links go, etc.
The grand overview should be in electronic form, though. A scanned hand drawing is fine. A photo of a whiteboard drawing is fine too.

For the logical network put comments whereever possible. On settings, VLAN configurations, server connections, account setups, ...
Again, the grand overview should be in electronic form.

I have found it useful that the information is timestamped, so you know when it was last valid.

Re:Documentation at your hands, and timestamped (1)

jimicus (737525) | more than 5 years ago | (#28091909)

Neither. I trust following the cabling and what the switch itself thinks is going on.

Anonymous Coward (1, Informative)

Anonymous Coward | more than 5 years ago | (#28091857)

http://www.spiceworks.com/
Good free tool.

Hire a Technical Writer (1)

billwrtr (1562281) | more than 5 years ago | (#28091889)

Why not hire a technical writer to work with you to develop meaningful documentation. That's what we do. With your help, we do it better/faster/cheaper than you ever could by yourself. And your successor -- if he/she reads it -- might even admit, "Oh!! this makes sense!"

If you are not mandated to document it (1)

mrmeval (662166) | more than 5 years ago | (#28091943)

All you are doing is wasting your companies money paying you salary for doing what they probably don't care about. The reason is because since there is no infrastructure for documenting it and keeping it current it will never be a part of the company. Without a clear chain of people up to the CTO monitoring that it is documented and kept safe you might as well use post it notes.

Sure keep your own documents but the company will just use your untimely death to buy new equipment, cut salaries and pay expensive consultants to fix the problem. Your death will cause someone to get a raise or fired or both.

The MACK(TM) Truck Rule (2, Informative)

Pathway (2111) | more than 5 years ago | (#28091947)

Ah, you're not following the MACK(TM) Truck Rule.

The MACK Truck Rule (MTR for short) is a measuring stick which we use do determine if a solution is good for us. Basically, it's an objective measurement of the level of expertiese required to do something. Basically, the MTR has you ask yourself (Or your team) the following question:

If the person(s) responsible for a task was suddenly hit by a MACK(TM) truck, How much time would it take for somebody else, untrained, to complete that task if needed?

If that amount of time is unreasonable*, It doesn't follow the MTR. Notice the caveat for unreasonable; this is the subjective part. What' unreasonable for one may be reasonable for another. This needs to be decided for yourselves.

Documentation always helps difficult tasks pass the MTR. So can good support. I try to leave a readme in the place where the installer is for a difficult program. I'm now begining to use FreeMind to map out networks and servers. I have a good ticket system for all our repairs. Hopefully these things will make things easier the day I want to take a vacation.

--Pathway

Ways I've documented networks (1)

JWSmythe (446288) | more than 5 years ago | (#28091959)

    I was wholly responsible for a large network. I usually had a few people working under me, so it was essential that we could find information about the servers.

    Our documentation was pretty simple. Actually, very simple. We had an internal web site set up so techs could message each other on what they were doing. It was a simple chat type interface. Every line was stored in a database.

    The company had several large sites, and tens of thousands of hosted domains. The internal web site had plain text files listing out the servers, grouped by city, then rack, with their name, their primary IP, and their function.

    A second list was a copy & paste from the PDU's, showing what machines were plugged in where.

    Both lists were linked from the web page for easy access, plus you could view them easily by logging into the server. As long as cat, less, or vi were working, they were easy to find.

    At another company, we set up a more elaborate page. It was entirely PHP/MySQL. It recorded all the details of the machine. IP, hostname, virtual IP's, manufacturer, model, serial, city, rack number, rack position, number of rack units the server occupied, the full output of dmidecode/vmidecode, it's function, versions of server software installed, etc. This was searchable, and you could print information on a single server, rack, all racks in the city, or any searched criteria. In addition, since some of the staff were freakin' illiterate, a second result page showed the information appearing like stickers on stock images of the machine fronts, including empty spaces. If the information was accurately maintained, you should be able to take a printout of the rack, and compare it directly to the rack, and everything would correspond.

      This second version made a very useful method to not need to create visio diagrams of every freakin' rack, and convince the people maintaining the diagrams to keep them updated with changes. Rather, if someone added or removed a machine, they were to enter the information into the warm fuzzy web interface.

    There are programs to do similar things, but I never found one that quite fit the business needs, so a few days of programming gave the interface. Populating information was pretty easy with a perl script, dmidecode, and a few other basic command line functions and DNS requests.

    Switches and routers were handled a little differently, but in a similar manner. Cisco 'show version' and 'show run' gave sufficient information to store everything about the way the switch ran, so in the event of a complete switch failure, a new switch could be dropped in place, the config could be copy & pasted into a terminal session, and it would be running exactly as expected.

   

The best help is a clean setup (1)

Gribflex (177733) | more than 5 years ago | (#28091967)

Any of the networks that I've worked with have always been for smallish companies (i.e. 80 employees) but often with very large offices. Things like museums, factories, mills, etc.

Without a doubt, the one thing that has helped me more than anything else has been when the person who came before me kept a very fastidious cabling system. By keeping the area as tidy as possible, and accurately (and informatively) labeling their cables and ports, it was very easy for me to work with the network.

Now, good labeling, and a tidy closet is not the same as quality documentation. But, it's probably analogous to well formatted code and useful code comments. (Where I think the OP is more looking for how to write the architectural specs.)

Wiki Wiki Wiki (5, Informative)

EEBaum (520514) | more than 5 years ago | (#28091979)

I have a wiki set up for the company I admin. Each server on the network has its own page, with a standard set of categories...
  • Purpose
  • Access (IP addresses, names, special ports)
  • Services provided (and descriptions of the services)
  • Maintenance (to do at intervals)
  • Quirks (stuff that tends to go wrong and what I've done about it)
  • Installation Notes (anything special I did when installing the server or any software on it)
  • Captain's Log (an entry for each incident involving this server, what its symptoms were, what I did to fix it, etc.)

I have a nicely formatted template page with all those categories set out. I also maintain a page of IP address assignments and an inventory of harware specs of all the machines in the office (which is helpful in the cases of "We need to reproduce a bug that only happens on ____ processor with ____ video card" and of "We're getting new machines. Who is in most dire need of an upgrade?").

I write down everything in these, and find myself referring to them very often. My predecessor gave me a Word document with all his notes in it, which has been very useful, and I used that as a starting point for my pages. The wiki has saved me a ton of time, kept me organized, and serves as a great reference for me and for the inevitable next admin.

The only caveat is if the wiki (or the server it's on) goes down. This has happened once, and my instructions for fixing the wiki were... on the wiki, so extra troubleshooting for me. Thus, I find it good practice to maintain a hard copy of the wiki pages, especially the page that tells how to fix the wiki.

I'm running this on Redmine, which has proven to be bleedingly simple to use and administer, and much easier than trac, which we used before. It's especially nice having it on the intranet, as I'll just have a browser open to the wiki as I work on systems and refer to and update it as appropriate. It's very handy to document exactly how I performed a strange or experimental installation of some software that I'll want to replicate later without making myself crazy, and I'll take the extra few seconds to retype the commands I just used into the wiki from anywhere in the building, though I probably wouldn't do the same into a Word doc.

It's not so much the mundane day-to-day that I find that important to document. It's the weird fixes, the trouble spots, the command line parameters, the installation procedures, the changes that shouldn't have fixed it but did, and the horrific chain reaction situations that make one piece of software crash because a seemingly unrelated piece of software has the wrong version of the 64-bit library. Things that take 4 hours to figure out and 3 seconds to implement... those are the ones to document, and those are the ones that I'd be kicking myself 20 months later for neglecting to write down. In an afternoon, any schmuck could walk into the building and figure out which network cable goes where. Documenting the strange bits (and the frustrations), though, can get a malfunctioning mail server back up and running in 3 minutes instead of 3 hours (which, of course, is secondary to good administration keeping the server from going down in the first place).

simply... (1)

luxifr (1194789) | more than 5 years ago | (#28091983)

...write down the passwords ...make graphics of the wiring with different symbols for clients, servers, including labels which tell the ip and dns name ...for servers: write down their function, which services run on them and step-by-step guides on how to do maintenance work ...document as visual as you can and it makes sense

Wiki/Google Apps (1)

fsterman (519061) | more than 5 years ago | (#28091991)

A wiki is what we used at my old networking company (Stability Networks [stabilitynetworks.com] ) that specialized in Small Business contract work. Recently I have grown rather fond of Google App's Wiki. It's free, relatively powerful, and (most importantly) very user friendly. I use it at my current company.

For the sake of job security... (0)

Anonymous Coward | more than 5 years ago | (#28092003)

Document only when necessary or ordered by your manager

Re:For the sake of job security... (4, Insightful)

gavron (1300111) | more than 5 years ago | (#28092049)

> Document only when necessary...

That's always.

Those who don't document don't have job security. They are an insecure leach sucking up a paycheck fearing -- and rightfully so -- the day they are going to be replace.

Those who DO document show their value to the organization, and should have no fear of being replaced. Their position is secure -- and should they go elsewhere -- they have something to show of and for their work.

I disagree with the parent vehemently and will say so based on years of experience as a techie, a techie manager, a manager of techies, an executive, and (thankfully) a techie again. You can never document too much, but those who don't cost the organization more in the long run each and every time.

Document. Document well and often. Ignore the parent.

Ehud

Use a wiki. Take pictures (1)

gavron (1300111) | more than 5 years ago | (#28092021)

Use a wiki. It will make it easy for you, your colleagues, and your [eventual] replacement to modify.

Take pictures. When discussing a piece of gear a picture is worth a thousand words. Instead of "the blue thingie halfway down the rack" or "that black thingie in the corner behind the laser printer" progressive pictures of the room, corner, and black thingie are priceless.

Remember that documentation isn't for the outside consultant or even for the guy or gal who replaces you (ooh, is she hot?) It's for YOU so you don't have to remember so that if you ARE hit by a bus, this is like the "My own guide for me to help me do my job." Document as if you know nothing. If it's a strange piece of gear include a copy of the config OR where the config is backed up AND how to get the config into it OR a link to the mfg website that tells the same.

Pretend the person reading the guide you write is NOT an expert. This won't hurt you or the outside consultant or your replacement (wait, IS she hot?) but it will help anyone who needs it.

Finally, make sure it's well-documented as to where the documentation is! I've done gigs where I've wasted days reverse engineering something only to find that somewhere in the pile of charlie romeo alpha poppa was a set of good fully-written but never-mentioned docs.

Ehud
P.S. Often a printout of same in a three-ring binder with a cover "WiKi docs as per 2009-05-26 online at http://ourdocs.mydomain.org/ [mydomain.org] " will have a dual purpose of providing DRP documentation (in case everything fails) as well as pointing to the real docs.
P.P.S. Ignore my being modded "troll", it's just that /. mods are herd animals.

Important (0)

Anonymous Coward | more than 5 years ago | (#28092023)

I worked as a technician for a mom and pop shop and the most frustrating thing for me was not labeling a switch or the wall mounts. Most MS networks are not that hard to administrate. Usernames and passwords are a given and you should be doing that anyway.

a special snowflake (1)

CAIMLAS (41445) | more than 5 years ago | (#28092055)

There are templates, and maybe they work for some networks, but from what I've seen, they don't work for an 'organic' network. Especially one which has been shoehorned into working by someone competent, and then allowed to languish at the heightened state for a while before being taken over by a competent person. (It's like what happens when you hit a cluster of dandelions with a non-mulching mower, sorta.)

There are a couple basic things to document, in my opinion.

* Passwords. They go in the lock box which you and your boss have keys to.
* Configuration files. Print them out and archive them.
* Infrastructure topology and routing. BIG BIG BIG. This stuff can go left undiscovered for years and takes a long time to actually dig into, especially if you don't have a central management system.
* hostnames (and IPs if apropos) with associated services
* Critical service list (and interdependencies).. granted sorta like the previous one but a bit different)
* Things that are on the "do not touch" list - eg. legacy applications - which will cause problems or have problems with certain infrastructural changes (eg. I know of one terminal client which can not exist on a DHCP network)
* Peculiar configurations on workstations used regularly, eg. in a dept. (see the previous point)
* The location of all assets
* The physical/digital location of ALL OTHER DOCUMENTATION!

The above should be in a printed binder and reviewed every couple months for changes. It should short and to the poitn so that your incumbent (or you) can use it as a quick reference.

You should also already have some way to track licenses and control the software installed on workstations; it's part of your documentation.

There are only a couple additional things I'd document (unless you're feeling bored and want to give your employer too much of an incentive to get rid of you for some young and inexperienced blood) as a small network administrator, IMO, to get out from under the "negligent" banner. Do more as time and desire permits, I suppose.

Personally, I think it's very important to document everything remotely interesting/useful, and to make it accessible in a fashion that's more useful than figuring out the 'neat'/solution again. Keeping a daily 'script' so you can backtrace what you did is potentially useful short-term (for your incumbent in the event you get hit by a bus, or a new coworker). Keeping a daily log of what you did is also useful.

Keeping a wiki from here-on-out of problems as they crop up (as well as documenting the more important information retroactively) is what I'd call the bare minimum.

Quick and dirty DR plan (0)

Anonymous Coward | more than 5 years ago | (#28092067)

Here is my advice for a quick an SUSTAINABLE documentation.

1) Create a Documentation folder on your central file server
2) Make sure that server is on a regular backup schedule to tape / alternate media
3) Create a macro or script that does the following each (at least once per month)

a. Telnet or SSH to network infrastructure using an account that is privileged as read only
b. Copy or capture the configuration file. In Cisco-esse it would be show run but you may want to do a show tech
c. If you have a central authentication server (AD / RADIUS / TACACs), copy the config file for these as well. If you do not have a central authentication server, then you should create strong root passwords - I recommend using an MD5 hash program on a pass phrase, and using the output of the hash. Write down the pass phrase and the hash type and result on a 3x5 card, fold, tape shut, put in an envelop that gets stored with other business critical documents at the very least, stored with the key control or in a 2 hr fire safe.
d. After you have all of the configuration files, zip the entire directory into one file.
f. Use SD card / DVD / alternate media and manually copy the zip file to physical media and put into a RED notebook binder. Make two copies. One to be placed by the ENTRANCE of the data room / server room. The other to be placed by the front desk or security and kept under lock and key. Off site data store of server tapes is a good idea as well.

This means that at the start of the you will need to burn a copy of the zip file twice and then replace the old files in the notebooks. If you schedule this properly, it will often consume no more than 30 min of your time.

Last thing to do is to create and IT disaster team. Have a once a quarter meeting that updates the IT staff and others outside of IT as to the location and response to a disaster.

This represents a stop gap, but low cost model that will allow most small to mid sized businesses to recover should there be an event that would damage operations (or you)

Load More Comments
Slashdot Login

Need an Account?

Forgot your password?

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>