RE: Decent docs
Title: RE: Decent docs I still like Mark Constables Wiki idea. Don't you believe it'll work, Alan? I never said that. I said if Mark sets up a Wiki site, and people find it useful, then it can be made the official FreeRADIUS Wiki site. Ahh, must have missed that one. Are you still planning to set it up, Mark? Serge.
Re: Decent docs
On Fri, 30 Nov 2001 19:44, Serge Maandag wrote: Are you still planning to set it up, Mark? Yes, here we go... all I've done so far is cut up doc/README into a few sections just to get some kind of feel for how this kind of interface can work. Any additipns and suggestions welcome... just freshly set up so I hope this URL actually works. http://wiki.netserva.com/?page=FreeRadius --markc - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: Decent docs
Serge Maandag [EMAIL PROTECTED] wrote: I still like Mark Constables Wiki idea. Don't you believe it'll work, Alan? I never said that. I said if Mark sets up a Wiki site, and people find it useful, then it can be made the official FreeRADIUS Wiki site. Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: Decent docs
Mark Constable [EMAIL PROTECTED] wrote: If that is not likely to happen (huge job) then at least accepting snippets of changes and additions that anyone might want to contribute and coordinating their inclusion into current docs is a more likely procedure. That requires time, and someone with a willingness to spend that time integrating changes people send to the list. Maybe this round of emails might alert a capable someone to the task of extending the manual properly in full DocBook format. I'm willing to give you CVS commit access if you're willing to coordinate the manual. Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: Decent docs
At 10:08 AM 11/28/2001 -0500, [EMAIL PROTECTED] wrote: Mark Constable [EMAIL PROTECTED] wrote: If that is not likely to happen (huge job) then at least accepting snippets of changes and additions that anyone might want to contribute and coordinating their inclusion into current docs is a more likely procedure. That requires time, and someone with a willingness to spend that time integrating changes people send to the list. Maybe this round of emails might alert a capable someone to the task of extending the manual properly in full DocBook format. I'm willing to give you CVS commit access if you're willing to coordinate the manual. On the subject of manuals... I'm taking what Chad Miller started in docbook format, converted to HTML and integrating the current 'doc/*' contents. It's just begun, but you can view the current state and it's progress at: http://www.segv.org/freeradius/toc.html Once I've got all of the current documentation incorporated, I'll be adding it to the site www CVS. -Chris -- \\\|||/// \ Chris Parker-Manager, Development Engineering \ ~ ~ / \ WX *is* Wireless!\ [EMAIL PROTECTED] | @ @ |\ http://www.starnetwx.net \ (847) 963-0116 oOo---(_)---oOo--\-- \ Without C we would have 'obol', 'basi', and 'pasal' - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: Decent docs
In article [EMAIL PROTECTED], [EMAIL PROTECTED] wrote: Mark Constable [EMAIL PROTECTED] wrote: Maybe this round of emails might alert a capable someone to the task of extending the manual properly in full DocBook format. I'm willing to give you CVS commit access if you're willing to coordinate the manual. I'm not going to write the docs but I did fix the Makefile and I added a README to the 'manual' CVS module Mike. -- Only two things are infinite, the universe and human stupidity, and I'm not sure about the former -- Albert Einstein. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: Decent docs
At 09:21 AM 11/28/2001 -0800, Chad Miller wrote: On Wed, Nov 28, 2001 at 09:31:51AM -0600, Chris Parker wrote: On the subject of manuals... I'm taking what Chad Miller started in docbook format, converted to HTML and integrating the current 'doc/*' contents. Ah! Something that I forgot to pass on! I have signifigant changes to the manual, that I never uploaded as they're not finished. Does someone want them? I hate committing unfinished work. Btw, Chris, 'db2html' does that rather nicely, as do 'jade' and 'openjade'. I dislike having to install additional things just to read a manual page, or to edit it. I'm just lazy I guess. :) I've got a tarball; who wants it? Fire away. -Chris -- \\\|||/// \ Chris Parker-Manager, Development Engineering \ ~ ~ / \ WX *is* Wireless!\ [EMAIL PROTECTED] | @ @ |\ http://www.starnetwx.net \ (847) 963-0116 oOo---(_)---oOo--\-- \ Without C we would have 'obol', 'basi', and 'pasal' - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: Decent docs
On Wed, Nov 28, 2001 at 11:39:05AM -0600, Chris Parker wrote: ... I dislike having to install additional things just to read a manual page, or to edit it. I'm just lazy I guess. :) The whole object of SGML and DocBook is to allow one to maintain a single source from which one can produce html, text, or typeset text. Once converted to html, much of the interesting information is lost (such as the ability to create automatic indexes). I've got a script that creates normal html, single-document html (easier to search and print), and text output from DocBook SGML input. The fact that DocBook automatically handles table of contents and the Index makes it far more useful than if I had to do all this manually. I must admit that I write most of my documentation initially in vi with standard groff ``mm'' macros, and have written an mm2sgml script that does a pretty good job of translating. I find it a lot easier to handle lists and tables this way than writing sgml manually, and I've been doing documentation with the mm macros for the better part of 20 years so I'm more comfortable with it. As an amusing aside, I was talking to Phil Hughes, publisher of Linux Journal, this weekend, reminiscing about the early days of the Seattle Unix Group, where the original board members were etc., and he noted that one of the original board members who worked for Phil's company SSC as a writer is now at Microsoft doing technical writing. Her boss at Microsoft was talking to her, and asked what she was doing that made her five to six times more productive than anybody else on the team. Her reply was that she writes everything with vi, then converts to M$-Word before submitting it. Bill -- INTERNET: [EMAIL PROTECTED] Bill Campbell; Celestial Software LLC UUCP: camco!bill PO Box 820; 6641 E. Mercer Way FAX:(206) 232-9186 Mercer Island, WA 98040-0820; (206) 236-1676 URL: http://www.celestial.com/ ``Liberty don't work as good in practice as it does in speeches.'' Will Rogers - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: Decent docs
At 10:35 AM 11/28/2001 -0800, Bill Campbell wrote: On Wed, Nov 28, 2001 at 11:39:05AM -0600, Chris Parker wrote: ... I dislike having to install additional things just to read a manual page, or to edit it. I'm just lazy I guess. :) The whole object of SGML and DocBook is to allow one to maintain a single source from which one can produce html, text, or typeset text. Once converted to html, much of the interesting information is lost (such as the ability to create automatic indexes). I've got a script that creates normal html, single-document html (easier to search and print), and text output from DocBook SGML input. The fact that DocBook automatically handles table of contents and the Index makes it far more useful than if I had to do all this manually. TOC/Indexing automagically could be useful. However, in order to use it, I have to learn a whole new markup language. Irony of ironies, the documentation for JADE ( the editor recommended on the docbook site ) sucks. I'll keep working on expanding what I have at: http://www.segv.org/freeradius/toc.html The html editor for mozilla is actualy very well done, and that's what I'm using. You can flip on the fly between editing raw markup html and wysiwyg, which is quite cool. You can save as HTML or TEXT ( where TEXT is de-htmlized and wrapped at 80 columns ). If someone else wants to put it in docbook format and maintain it, feel free to do so. :) -Chris -- \\\|||/// \ Chris Parker-Manager, Development Engineering \ ~ ~ / \ WX *is* Wireless!\ [EMAIL PROTECTED] | @ @ |\ http://www.starnetwx.net \ (847) 963-0116 oOo---(_)---oOo--\-- \ Without C we would have 'obol', 'basi', and 'pasal' - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: Decent docs
Hi, Chris. On Wed, Nov 28, 2001 at 01:42:02PM -0600, Chris Parker wrote: However, in order to use it, I have to learn a whole new markup language. Irony of ironies, the documentation for JADE ( the editor recommended on the docbook site ) sucks. Ugh. That site must really suck, if it led you to believe jade is an editor. 'jade' is a renderer. It will render the DocBook SGML to any format that it has a backend for (usually HTML, PDF, and RTF). Docbook really is nice. Please try it. An excellent site is URL: http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html . Here's how useful DocBook is: O'Reilley's authors use Docbook (usually). ORA used jade on the very same source to render it to ROFF for the print-house and HTML for the webmonster. Both look really good. I'm becomming to grok the Buddha-nature of DSSSL (we use it at work), so feel free to ask me to make the rendering phase do what you want. Attached is the single-page HTML rendering of what I have so far. - chad -- Chad Miller [EMAIL PROTECTED] url: http://web.chad.org/home/ ``Is it wrong to donate Kool-Aid to one's favorite kook organizations when The Comets come around?'' - C. M. Title: FreeRADIUS Operating Manual FreeRADIUS Operating ManualCopyright 2001 by The FreeRADIUS ProjectTable of Contents1. Overview1.1. Compilation and Installation1.2. Execution2. Configuration Concepts and Files2.1. Configuration Structure and Parsing2.2. Actual Sections and Variables2.2.1. Five Execution Sections2.2.2. Top-level Variables2.2.3. Proxy Section2.2.4. Thread Pool Section2.2.5. Clients Section2.2.6. Module Section3. TroubleshootingA. Format of the users fileB. Username Collision HandlingB.1. AuthenticationB.2. AccountingC. String TranslationIndexList of Examples1-1. Compiling and Installing FreeRADIUS2-1. Sections, Subsections, and Comments2-2. Defining proxy realms2-3. Listing for a RADIUS clientB-1. Collision in a users fileB-2. Collision information in a passwd fileChapter 1. Overview FreeRADIUS is an implementation of the RADIUS protocol. It aims to be a free, fast, robust, feature-rich server. Livingston's RADIUS server, the first decent free (libre) RADIUS server, is the basis of most RADIUS implementations today. From it grew many attempts at improvement and redesign. One of those reimplementations, Cistron's, became popular for its features and rapid development and it became a staple for those in the ISP business who were dissatisfied with other servers. Eventually, Cistron's server was well entrenched, and development and redesign issues begat The FreeRADIUS Project. Cistron's server is still in usage, but active development on it has ceased and been moved to development of FreeRADIUS The RADIUS protocol is a means of authentication and accounting sessions, usually of dialin users, but feasably of any kind of session. It does not address other concerns like billing, user organization, or data management. A RADIUS server listens on a network for authentication requests, and upon receipt of requests, either answers with a rejection or with confirmation and optional session attribute suggestions. Upon recipt of an accounting packet, it can store evidence of the session starting or terminating. 1.1. Compilation and InstallationThe FreeRADIUS server is written in the C programming language, and a POSIX environment with a ANSI C compiler and GNU Make is necessary to create an executable from source code. There are plenty of optional features of the server that require additional software to be installed for one to use those features. At present, The FreeRADIUS Project does not distribute binary packages; you might get some from your OS vendor or by asking the freeradius-users email list. All the components necessary to build a binary are freely available, though, so you should be able to build it yourself. One should get the server's source code by reading the instructions at http://www.freeradius.org/getting.html. The steps for compiling and installing from FreeRADIUS source (in an example ~/freeradius directory) should be something like... Example 1-1. Compiling and Installing FreeRADIUSfoo:~/freeradius$ ./configure --help (browse the options) foo:~/freeradius$ ./configure [options] loading cache ./config.cache checking for gcc... gcc checking whether the C compiler (gcc ) works... yes checking whether the C compiler (gcc ) is a cross-compiler... no checking whether we are using GNU C... yes checking whether gcc accepts -g... yes checking how to run the C preprocessor... gcc -E [...] foo:~/freeradius$ make make[1]: Entering directory `/home/bar/freeradius' [...] foo:~/freeradius$ su Password: foo:~/freeradius# make install make[1]: Entering directory `/home/bar/freeradius' [...] 1.2. ExecutionThe server executable should be at
Re: Decent docs
Mark Constable [EMAIL PROTECTED] wrote: My naive expectation is that when people try to configure servers, they *read* the configuration files, in order to make any necessary local changes. That's assuming a naive user knows enough about realms to know to read something in the doc/ dir called realms. That's not what I said. There is a *configuration* file called 'realms'. And reading the normal 'radiusd.conf' will eventually cause you to run into the word 'realms'. I generally avoid documentation for free software projects, because they're usually as bad as those distributed with FreeRADIUS. I find that reading the configuration files, and trying different configurations, is usually much more helpful. An experienced user has the luxury of incrementally increasing their knowledge, a new user is trying to figure out WTF is going on and where to start to even make a start. I gave a talk at the local Unix group a few years ago, describing just how to do this. The summary is this: use grep, find, locate, and any other information retrieval tool you have. They allow you to quickly root through files, looking for key words, and ignoring false positives. Anyone using this method is a Unix guru. I've seen studies which demonstrate this. Sure, just read everything and eventually it'll start to make sense but that could be a dozen hours (inc rfcs) and I don't know any newbies that dedicated in any discipline. HOWTOs with lots of examples would be brilliant. As always, submissions are welcome. We *desperately* need more documentation and examples. The problem is that after most people as one or two questions on the list, their problems are solved, and they go away. They contribute nothing further, and aren't interested in contributing, either. So the only people contributing are the ones who are interested, and there are *very* few of those. This is something where the non-CVS-enable-developers could contribute back to the project. I hope I can nudge this along. Unfortunately I do not know enough about DocBook (nor really want to) to do any serious manual writting but at least putting all current texts (or links to them) in one place on the web might help... and doubly so if they are in Wiki where anyone can easily make changes... Set up a prototype web site. If it's used and usefull, it can be rubber stamped as official. as opposed to trying to run make on a 60k docbook that requires 25 mb of tex/jade gunk before being able to read anything at all (of the manual that is). Well, that's why I never made any changes to the docbook stuff. I couldn't figure out how to rebuild it. BTW Alan, I'm a python biggot now... PHP what? :-) Hey, whatever works. Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
