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

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

[Oskar Andreasson]

Hi All,

Just wanted to let everyone know that the ipsysctl-tutorial is released 
in a kind of super-pre-beta version or so. It's far far from complete, it 
probably contain 500 errors per word that it consists of, but.... I'd just 
like to see if people would like to read through parts of it and see what 
they think of it? This is the URL to the current version:

http://ipsysctl-tutorial.frozentux.net

Is this document worth the effort? Is this anything along the lines what 
you have wished for? Is there anything missing (yes, tons that I know 
of=))? Find any bugs or errors on my part? 

I will be totally honest, this document probably took me several hundreds 
of hours getting this far, since I had to pretty much read up on every 
single variable in the source code. Considering that I am a fairly bad 
coder, this took some considerable part of the time:). I am pretty damn 
certain that this has led to hundreds of errors, and people will probably 
want to kill me for some of them.

Thanks for any kind of feedback!

-- 
----
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/

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

[Mikhail Romanenko]

08.10.2002 0:01:55, Oskar Andreasson <blueflux@koffein.net> wrote:

>Hi All,
>
>Just wanted to let everyone know that the ipsysctl-tutorial is released 
>in a kind of super-pre-beta version or so. It's far far from complete, it 
>probably contain 500 errors per word that it consists of, but.... I'd just 
>like to see if people would like to read through parts of it and see what 
>they think of it? This is the URL to the current version:
>
>http://ipsysctl-tutorial.frozentux.net
>
>Is this document worth the effort? Is this anything along the lines what 
>you have wished for? Is there anything missing (yes, tons that I know 
>of=))? Find any bugs or errors on my part? 
>
>I will be totally honest, this document probably took me several hundreds 
>of hours getting this far, since I had to pretty much read up on every 
>single variable in the source code. Considering that I am a fairly bad 
>coder, this took some considerable part of the time:). I am pretty damn 
>certain that this has led to hundreds of errors, and people will probably 
>want to kill me for some of them.
>
>Thanks for any kind of feedback!
>

I am new to LARTC and such tutorial is very usefull for me, and (I hope)
guys like me. Thank you for your job.

Mikhail.





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

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

[Don Gould]

> Is this document worth the effort?

YES  (caps intended!)

> Is this anything along the lines what you have wished for?

Getting closer!

> Is there anything missing (yes, tons that I know of=))?

Yes, I couldn't find instructions on how to help you with the document. :)

> Find any bugs or errors on my part?

I have started reading it and already found some very minor errors
(typo's) but didn't know how best to take part.

Please let me know how I can be of assistance.

> I will be totally honest, this document probably took me several
> hundreds  of hours getting this far, since I had to pretty much read up
> on every  single variable in the source code. Considering that I am a
> fairly bad  coder, this took some considerable part of the time:). I am
> pretty damn  certain that this has led to hundreds of errors, and people
> will probably  want to kill me for some of them.

If I'm understanding what I've already read in the first 10 pages
correctly then it has already been of more value to me than you can hope
to imagine in this life time! :)

Cheers DiG


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

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

[Oskar Andreasson]

Hi Don,

Short reply. It seems that the request for feedback got people 
overwhelmed... or perhaps it's just me who's overwhelmed:). Anyways, I 
will continue writing on the document.

As for the question about helping out.... for typos etc, it would be 
extremely appreciated if you download the Docbook SGML source and tar 
-xzvf the package. After that, make a copy of the source dir into 
ipsysctl-tutorial.old. Do all the changes in the original 
ipsysctl-tutorial directory, and when you feel you are done, go back to 
the base directory and do something like this:

diff -ur --exclude=CVS ipsysctl-tutorial.old ipsysctl-tutorial > file.diff

This should create a blah.diff file containing all the differences in 
unified diff format. Send that one over to me, and I should have 
everything that I need.

When it comes to larger changes (e.g., a missing admonition, large 
sections of text, or things that you don't want to do yourself), you may 
either do as above and I will see what you think is wrong and can take a 
look at it myself... Or you could just send a brief description of the 
problem and proposed changes, and I will look at it:)

I hope this explains how you may help. I will add something about this to 
the tutorial or somewhere there as well. Thanks for notifying about this!

//Oskar

On Tue, 8 Oct 2002, Don Gould wrote:

> > Is this document worth the effort?
> 
> YES  (caps intended!)
> 
> > Is this anything along the lines what you have wished for?
> 
> Getting closer!
> 
> > Is there anything missing (yes, tons that I know of=))?
> 
> Yes, I couldn't find instructions on how to help you with the document. :)
> 
> > Find any bugs or errors on my part?
> 
> I have started reading it and already found some very minor errors
> (typo's) but didn't know how best to take part.
> 
> Please let me know how I can be of assistance.
> 
> > I will be totally honest, this document probably took me several
> > hundreds  of hours getting this far, since I had to pretty much read up
> > on every  single variable in the source code. Considering that I am a
> > fairly bad  coder, this took some considerable part of the time:). I am
> > pretty damn  certain that this has led to hundreds of errors, and people
> > will probably  want to kill me for some of them.
> 
> If I'm understanding what I've already read in the first 10 pages
> correctly then it has already been of more value to me than you can hope
> to imagine in this life time! :)
> 
> Cheers DiG
> 
> 
> _______________________________________________
> LARTC mailing list / LARTC@mailman.ds9a.nl
> http://mailman.ds9a.nl/mailman/listinfo/lartc HOWTO: http://lartc.org/
> 

-- 
----
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/

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

[Don Gould]

Hi Oskar,

I'm copying this response back to the group because others may wish to add
a view.

(Comments that start with >> were made by DiG, comments that start with >
were Oskar's responses.)

>> I am finding some of the syntax hard to understand in places.

> What kind of syntax, the computer syntax or my writing syntax?

It was your English I had trouble with.

> English isn't my "main language"

I am so glad you said that! :)  I couldn't think of a polite way to ask.

This is not a problem.  Now I know this I understand how to best help.

Spelling is not my strong point, but when I concentrate I can get the
words in the right order.

>> 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.

Writting everything in third person can be hard when documenting and
distances your from the reader.

We are fighting more than one battle here.

1. We must educate the user.

2. We must make the user our friend.

We are writting this document out of love not because we see a huge pot of
gold at the end.  Yes, we might get to a huge pot of gold but that is not
our main focus.

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

>> 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.

>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.

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).

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.

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.

>> 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.

>> 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.

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.

>> 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.

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.

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

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.

Cheers DiG





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

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

[Oskar Andreasson]

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/