Re: [LARTC] [Almost OT] ipsysctl-tutorial pre-beta version

[Oskar Andreasson <blueflux@koffein.net>]

Don,

On Wed, 9 Oct 2002, Don Gould wrote:

<snip>

> 
> >> The document also changes from first person to third person in places.
> 
> > Ugh.... at work I am forced to write in first person, but when I write
> > "as  I wish" I generally tend to write in third person. Don't ask me
> > why. Which  form would you think is the best to use? First or third?
> > Personally, I  think third person sounds more ... "ellegant", but I am
> > in no good  position to make a judgement since english isn't my main
> > language=).
> 
> Consistency is my only issue.

Will be fixed for the next version of the tutorial. Remember, this was a 
"beta" version. It will be written in first person, even though I don't 
find it appropriate for now. 


> We want to partner with our reader.  They in turn will become passionate
> about sharing what we already know with other people.
> 

To play the devils advocate here, no. I don't want to partner up with the 
readers. I have had my fair share of mail questions already, which don't 
pay the bills, stops you from actually getting anything written, and so 
on. The worst part is when the "mailee" is rude and intruding as well 
(I've actually had a couple of people getting pissed off at me because I 
replied to them that I didn't have the time to answer them, so they winded 
up spamming me with >500 copies etc).

> >> Who the intended reader? This was unclear to me.
> 
> > The introduction/preface in general needs to be a little bit reworked.
> > To  be fairly honest, I don't know who the intended reader is.
> 
> Ok, I can help with that to start with and offer some suggestions.
> 

No need, I will be working on the introduction right now. I've been 
meaning to polish it a little bit for the last couple of weeks but never 
got around to it.

> >In general, it  should be someone with medium through advanced knowledge in
> > TCP/IP and  networking, as well as in Linux administration.
> 
> I disagree with both those points.  I will explain why a little bit
> further down...
> 
> > I don't think it will fit  in for anyone who barely know how to set up
> > a network under linux. 90% of  these variables are very fragile and may
> > make things go totally "tits-up"  if you excuse the expression.
> 
> I also disagree with the two points you have made above.
> 
> 1. Foundation Stones.
> 
> The area you are talking about forms part of the foundation stones of Linux.
> 

No, they don't. ifconfig/iproute2/route are the corner stones, and how to 
load a device module. At least from a john doe perspective. There are 
_possibly_ 10 variables of interest to john doe in the ip sysctls:

ip_forward - of course
icmp_echo_ignore_all
icmp_echo_ignore_broadcasts
icmp_ignore_bogus_error_responses
tcp_syncookies
conf/*/rp_filter
conf/*/proxy_arp

Other than that, I can't actually find anything of interest to John Doe
(atm!), except if he has a interest in networking, he is a system
administrator, or is a network developer of one sort or another. Do note, 
this may not be a complete list, but in 99.999% of the cases, these 
variables should be enough, if any are needed to change.

> 2. Target Audience.
> 
> The target audience should be anyone with a reasonable grasp of network
> concepts (ie two or more computers linked together is known as a network).

That would mean duplicating everything from TCP/IP Network Administration 
(O'reilly) to TCP/IP Illustrated all the way through the documents by 
Sally Floyd and van Jacobsen. Do you seriously mean that I should redo the 
work already done and put it into a "new" book covering 5000 pages, not 
even covering the hardware bits?

> 
> 3. Information Leads to Understanding.
> 
> Publishing the information with a good explanation will lead to the
> responsible reader making an informed decisions.
> 
> An educated user won't harm their systems if we provide them with enough
> information in a format that leads them to understanding it.

Agreed, but if they need "that" kind of information, they should look 
somewhere else. I am not about to explain "this is what an IP address 
looks like" or "this is how the 'ls' command works". It simply falls 
outside of the scope of the ipsysctl.

Before reading this, they should already have a fairly good grasp of IP 
networks and so on. 

> 
> 4. Our role.
> 
> Our role is to provide the information.
> 
> Having provided the reader with the information it is the users role to
> decide if they are confident to use the information to make changes to
> their system.
> 
> We are stewards not wardons.

Agreed, but I am not about to embark on a single man mission to mars. This 
document should preferably contain information about the sysctl to begin 
with, and how to use it. Sure, there can be links and examples of where to 
find the necessary understanding needed to comprehend the document in the 
beginning, but I will simply not write that kind of stuff now. 

> 
> >> At the start of the document you have made a number of assumptions
> >> about your reader which makes the opening very hard to follow (I had
> >> to read it 4 or 5 times.)
> >
> > Hmmm, where do you mean? What kind of assumptions?=) Let me know, and I
> > will try to take care of them.
> 
> I will redraft the opening for your consideration.
> 
> I think that would be quicker than my attempting to explain my thoughts.

Ok, do so. However, I would urge you to wait for a couple of weeks if you 
don't mind. I will be rewriting the introduction a little bit, adding 
sections about "necessary pre-knowledge", what to expect of this document 
etcetera. 

> 
> >> At 32 I'm a programmer who's worked with IT for more than 15 years but
> >> mainly with  Microsoft products.
> 
> > Well, I'm 23 and been in IT for 5 years. Not impressive I assume, but I
> > try my best, and writing means that I learn much much better than any
> > other way.
> 
> Thank you for the background.
> 

That's not really my background, just the one in the actual "trade" of it. 
But that's just a sidenote, so I won't get into it:). Don't judge the dog 
by the hairs.

> Like you I try my best in a less than perfect world.
> 
> I choose to share my background with you to help you work out in your own
> mind how you can best use my skills in your project.

Hey, it's not my choice to use you, it's you who choose to help. That's 
what open source is about to me. You know your limits better than I do, 
hence you should ask yourself what you can do, then ask if you may do it 
or if anyone else is doing it. If noone else is doing it to my knowledge, 
you do it to the best of your ability and send it in to me when you're 
done.

Remember, this is only my way of doing things, and others may be 
infuriated at this way of dealing with shared work:).

> 
> >> I have written many instruction manuals that have been used by people
> >> older than my parents with very few computer skills.
> >>
> >> I found your document very useful so far because it fills a void for
> >> people like me who have a very good technical back ground and common
> >> sence but are new to the linux side of things.
> >
> > Thanks, very much appreciated:). In general, I would say that these
> > variables are not meant for the "new comers" really. To put it in the
> > words of Alexey Kuznetsov, "the algorithms are only understood by a
> > handful of people in the world, and people should not need understand
> > them. Some of the variables should not even be touched without the
> > expertise of these persons".
> 
> System administrators often make the wrong changes to a system because
> they don't completely understand what the setting does and don't know that
> the setting they are changing shouldn't be changed.
> 

Agreed, and sysadmins are one of the audiences of this document. However, 
if you already are a sysadmin, you should at least know what TCP/IP is, 
and routing fundamentals. I will not teach them that (yet), at least not 
in this document.

Some of the algorithms are, however, impossible to comprehend from a
compact document like this. To use the tcp_ecn variable as an example this
time, there are some 3-4 RFC's describing it to my knowledge, and tens, if
not hundreds, of articles describing what it is, how it works and why it
was implemented.

And to redo the example of tcp_fack, which operates on top of the SACK 
option, and which also uses timpestamps etc. All three of these are 
described in countless articles, RFC's and documentation. I have printed 
out a few of the most important articles and RFC's on this topic, read 
them, and so on. They are currently contained in two "binders" (right 
word?), which are crammed up totally with them. 

At this point, I am not writing a "tcp_fack tutorial" nor a "tcp_sack
tutorial", and most definitely not a "networking with Linux for beginners
through high-tech gurus". I hope you see my point.

> A common mistake made by administrators is to change one setting with out
> making changes to another.  This happens because they don't realise the
> impact of what they are changing.
> 
> > I wish I could claim to fully understand the algorithms, but I don't. I
> > understand them partially, and I try my best to explain the basic
> > meaning  of them. But.... there is no sense really in trying to explain
> > what the  tcp_fack variable does from scratch to a complete newbie, who
> > has never  used or read about networks or linux before. He should start
> > with  something more basic, such as TCP/IP Network Administration and
> > Linux  Unleashed before trying to understand this text.
> 
> As expressed above, this area forms the foundation stones of the system.

No they don't imnsho. There are possibly 10 or so variables that john doe 
needs to know about. No more, and that is only if they are really into 
networking. If they have only one machine and don't consider security as 
an issue, they don't need to think about it at all.

> 
> When a good music teacher starts teaching you to play they start with
> scales (a series of musical notes).

For the sake of not trying to take on a lifetime project, I can not do 
that. 

> 
> I agree this is not a starting point.  However the newbie should be able
> to start here, understand the information and then take that with them as
> they move on.

I totally disagree. A newbie should not and could not understand these 
variables. I can't start by explaining that "this is a network cable. Over 
a network cable, information is sent via electrons". Perhaps this is 
taking it to the extreme, but that is pretty much how far you would have 
to take it if following your directions.

I hope you don't take me wrong. What my intentions are for now, is to make 
a proper introduction, explaining what the reader is supposed to know etc. 
Then a robust and fairly well evolved reference to all the IPv4 options 
and possibly a few scripts with the most common variables that one may 
want to change, that can be used together with iptables/iproute2 etcetera. 
I promise, this will be more than enough to keep me busy for the coming 
half year or so. After that I am more than willing to look into other 
directions and to add more subjects to it. 

I hope you understand my reasoning with not wanting to take on too much 
work straight away. This document will take enough time to write as it is.

-- 
----
Oskar Andreasson
http://www.frozentux.net
http://iptables-tutorial.frozentux.net
http://ipsysctl-tutorial.frozentux.net
mailto:blueflux@koffein.net

_______________________________________________
LARTC mailing list / LARTC@mailman.ds9a.nl
http://mailman.ds9a.nl/mailman/listinfo/lartc HOWTO: http://lartc.org/