Write Your Name In Your Clothes!

I’ll bet that at one time or other in your life, you’ve had your name written in your clothes. You know what I’m talking about – either you buy some specially made labels to stick in your clothing, or you use one of those laundry markers to scrawl it on the care label. Usually this is exclusive to children’s clothing, as perhaps they are most likely to leave their clothing lying around for somebody else to find; if their name is in it, the finder can clearly identify who the item belongs to and everybody will be happy, especially Mom and Pop who paid for the thing.

As adults however, it seems most of us don’t label our clothes – we assume that we are too clever to lose anything, so we become careless about labeling it. In reality, writing your name in your clothes takes seconds and may save you down the line, so it’s kind of stupid not to.

I know what you’re thinking – what on earth does this have to do with networking? Let me explain…

As a consultant, I spend my time going into networks I don’t know and I have to reverse engineer them to some degree before I can make a change safely. In doing so, I often find myself having to figure out what on earth the previous engineer(s) were actually trying to accomplish with particular parts of the configuration – and I often end up dumbfounded and shaking my head. I mean, I understand what the configuration does, but understanding the intent is quite another thing.

So here’s my plea to all router and switch engineers – when you’ve finished writing your name in your jacket, let’s be sure and do the same for the network devices you maintain. I’m a big proponent of self-documented networks, and this is not entirely altruistic as you can imagine – if it’s well documented, I can understand what’s going on without having to either guess or bug the network team and waste their time trying to recall why something was put in.

Let me explain what I’m on about. Here’s an example of a switch interface configuration snippet that’s fairly typical of what I find:

vlan 17
!
interface FastEthernet 1/3
 switchport
 switchport mode access
 switchport access vlan 17
!
interface Vlan 17
 ip address 10.17.3.1 255.255.255.0
end

Um, ok. So an unlabeled port is attached to VLAN 17 which is, um, not named, and the SVI for VLAN 17 is, well, I see the IP address but still have no clue as to what this represents. Here’s the kind of thing I’d prefer to see:

vlan 17
 name DB_Svr_BackEnd
!
interface FastEthernet 1/3
 description SRVDB01A-hme0
 switchport
 switchport mode access
 switchport access vlan 17
!
interface Vlan 17
 description Database Server Back Ends
 ip address 10.17.3.1 255.255.255.0
end

I suspect that many of you are currently saying “That’s ridiculous! I always put a description on my interfaces!” And if you do, thank you! How are you with route-maps and ACLs?

route-map REDIST permit 10
 match ip address 7
!
router ospf 1
 redistribute bgp 65000 subnets route-map REDIST
!
access-list 7 permit 10.1.1.0 0.0.0.255
access-list 7 permit 172.16.0.0 0.0.255.255

Again, my cup overfloweth not. I see what you’re doing, but have no information that might guide me as to why you chose those subnets to redistribute, or what they are. I would also argue that calling a route-map “REDIST”, while marginally helpful, doesn’t fully describe its purpose does it? Imagine you’re seeing this for the first time; wouldn’t it be nicer to see something like the following configuration instead?

route-map BGP_TO_OSPF_REDIST permit 10
 description Advertise Data Center #3 subnets in OSPF
 match ip address DC3_Subnets
!
router ospf 1
 redistribute bgp 65000 subnets route-map BGP_TO_OSPF_REDIST
!
ip access-list standard DC3_Subnets
 permit 10.1.1.0 0.0.0.255
 permit 172.16.0.0 0.0.255.255

I think that’s a little clearer; and of course you can add additional terms to the route-map and give each one a description as required. I’d argue also that you should use a prefix-list rather than an ACL for most route redistribution, but that’s probably a discussion for another post.

There is a caveat to this of course – for it to work, you have to trust (or enforce) that all engineers honor the naming/descriptions, and don’t get lazy and just tag DC2 routes on to the DC3 ACL because it’s easier than creating a new DC2 ACL and route-map entry. In other words, you can’t do this stuff in isolation or the information shifts rapidly from helpful to misleading. A good change control / script review process can help with this of course, as well as regular beatings with a cluestick (or repurpose a LART as an EART for the Engineers).

Do you label your prefix-lists?

ip prefix-list DC3_Subnets description Data Center 3 (Harlow) Subnets
ip prefix-list DC3_Subnets seq 5 permit 10.1.1.0/24
ip prefix-list DC3_Subnets seq 10 permit 172.16.0.0/16

It’s worth noting that you can only have one description in a prefix-list; if you try adding a second it simply overwrites the first one. Still, it’s better than nothing.

Do you name your static routes?

ip route 1.1.1.0 255.255.255.0 192.168.1.1 name DMZ_via_FW01

NXOS users can cry now, unless the ability to name static routes finally got added; it was certainly missing in 4.2 and I could kill Cisco for missing something so basic from NXOS. IOS users just need to remember that the name either has to be contiguous (e.g. use underscores or similar) or needs to be in quotes, e.g.

ip route 1.1.1.0 255.255.255.0 192.168.1.1 name "DMZ via FW01"

As I suggested above, smart self-documentation extends to naming your access-lists, prefix-lists, route-maps and so forth intelligently as well. One school of thought says that you should use a prefix to indicate the object type, like in programming when you name a variable to indicate its type, e.g. strName for a string containing a name. That can work for sure – it should certainly ensure that you are unambiguous about which object you are referencing in a command, although logically speaking you could argue that it’s obvious based on context whether you’re referring to the prefix-list DMZ_SUBNETS or the route-map DMZ_SUBNETS (the latter of which, however, is badly named because it doesn’t indicate what the route-map is intended to do 🙂 ).

Some common sense is required before you jump in, however. When you write your name in your clothing, you look at the label to figure out how big it is, determine whether you’re going to just put your initials, your whole name, or maybe just your last name, and you figure out how big you can write in order for it to fit in. Without wishing to stretch the analogy too far, the same applies when you start naming configuration elements.

route-map BGP_TO_OSPF_REDIST_FOR_DC3 permit 10

This route-map, for example, is likely to have a short shelf-life – the moment you want to redistribute anything other than DC3 routes from BGP to OSPF, the route-map name becomes meaningless and now you have the exciting task of either creating a newer and more appropriately named route-map and replacing that one, or you go the lazy route and just add those DC2 routes in there anyway because it’s easier. In other words – plan ahead; be generic with the route-map name, but be specific when creating descriptions for each term you add.

If you think ahead, your router configurations can act like a guide book for anybody new looking at the configurations; you can reduce on-boarding times for new team members because they’ll understand the network more easily. Troubleshooting becomes easier because everything is clearly labeled. Changes are less risky because it’s harder to misunderstand what’s going on. And perhaps most importantly (selfishly speaking), when I – or some other third party – comes in to help out with something, my brain will hurt just a little less.

OK, I think I’ve said enough. I’ll get my coat.

Wait a second – *checks label* –  I believe this coat is yours…

 

Do you self-document? What are your tips for good config maintenance?
Let me know in the comments!