* Re: [LARTC] [Almost OT] ipsysctl-tutorial pre-beta version
2002-10-07 18:01 [LARTC] [Almost OT] ipsysctl-tutorial pre-beta version Oskar Andreasson
2002-10-08 2:11 ` Mikhail Romanenko
2002-10-08 9:27 ` Don Gould
@ 2002-10-08 12:01 ` Oskar Andreasson
2002-10-09 11:37 ` Don Gould
2002-10-09 14:28 ` Oskar Andreasson
4 siblings, 0 replies; 6+ messages in thread
From: Oskar Andreasson @ 2002-10-08 12:01 UTC (permalink / raw)
To: lartc
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/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [LARTC] [Almost OT] ipsysctl-tutorial pre-beta version
2002-10-07 18:01 [LARTC] [Almost OT] ipsysctl-tutorial pre-beta version Oskar Andreasson
` (2 preceding siblings ...)
2002-10-08 12:01 ` Oskar Andreasson
@ 2002-10-09 11:37 ` Don Gould
2002-10-09 14:28 ` Oskar Andreasson
4 siblings, 0 replies; 6+ messages in thread
From: Don Gould @ 2002-10-09 11:37 UTC (permalink / raw)
To: lartc
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/
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [LARTC] [Almost OT] ipsysctl-tutorial pre-beta version
2002-10-07 18:01 [LARTC] [Almost OT] ipsysctl-tutorial pre-beta version Oskar Andreasson
` (3 preceding siblings ...)
2002-10-09 11:37 ` Don Gould
@ 2002-10-09 14:28 ` Oskar Andreasson
4 siblings, 0 replies; 6+ messages in thread
From: Oskar Andreasson @ 2002-10-09 14:28 UTC (permalink / raw)
To: lartc
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/
^ permalink raw reply [flat|nested] 6+ messages in thread