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/
Mikhail Romanenko
2002-Oct-08 02:11 UTC
Re: [Almost OT] ipsysctl-tutorial pre-beta version
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/
> 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/
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/
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/
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/