Unix administration - Documenting a server conf

Author

Documenting a server conf

andrea

2007-10-16, 7:30 am

Are there any nice tools to document the configuration of a server?
I want to write down every operations I do, with comments and most
important configuration files.

Any useful program?
Maybe just latex?

Svn would be really nice (for commenting and see diffs) but I can't
use it for system files...

Sylvain Robitaille

2007-10-16, 1:28 pm

andrea wrote:

> Are there any nice tools to document the configuration of a server?

I tend to use vim (or vi if vim is unavailable) to document any changes
I make to a system's configuration. It works beautifully, I have the
fallback to vi when vim is unavailable, and the resulting files are small
and readable on any new system. I also can easily duplicate actions on
different systems by simple means of copying and pasting between xterms
when necessary.

I hope that helps ...

--
----------------------------------------------------------------------
Sylvain Robitaille syl@alcor.concordia.ca

Systems and Network analyst Concordia University
Instructional & Information Technology Montreal, Quebec, Canada
----------------------------------------------------------------------

andrea

2007-10-16, 7:22 pm

On 16 Ott, 18:33, Sylvain Robitaille <s...@alcor.concordia.ca> wrote:
> andrea wrote:
>
> I tend to use vim (or vi if vim is unavailable) to document any changes
> I make to a system's configuration. It works beautifully, I have the
> fallback to vi when vim is unavailable, and the resulting files are small
> and readable on any new system. I also can easily duplicate actions on
> different systems by simple means of copying and pasting between xterms
> when necessary.
>
> I hope that helps ...
>
> --
> ----------------------------------------------------------------------
> Sylvain Robitaille s...@alcor.concordia.ca
>
> Systems and Network analyst Concordia University
> Instructional & Information Technology Montreal, Quebec, Canada
> ----------------------------------------------------------------------

Yes vim it's fine, I use it for system files, but how do you organize
the informations?
Something like that?
-- 12 OCtober --
- change 1
- change 2

I think with latex I could get a much better result, and I don't need
to write stuff directly on that machine.
My question is how to organize informations...

Michaël Grünewald

2007-10-16, 7:22 pm

andrea <kerny404@gmail.com> writes:

> Are there any nice tools to document the configuration of a server?
> I want to write down every operations I do, with comments and most
> important configuration files.

I am currently thinking about using NOWEB for this purpose. Noweb
is a literate programming tool. As literate programming is not a very
common topic, I will give you a taste of it (just in case) before
discussing how it could be used for your problem.

In case you are not familiar with this kind of tools, literate
programming tools are designed to produce both a program and its
documentation from a common source file. Note that the point of view
is rather different from the one used in tools like DOXYGEN where
documentation lives as a parasite in program comments.

The most famous literate programming tool is certainly the pair
CWEAVE, CTANGLE, from a common source CTANGLE will produce a C program
and CTANGLE a TeX file documenting the program. Unlike CWEAVE/CTANGLE,
the NOWEB program do not insist producing C programs and TeX-able
documentation. It is therefore less specialized but more easy to use
and more adaptable to different tasks.

To give a concrete example of the (hypothetical) usefulness of NOWEB
is managing administrative files, let's discuss an (hypothetical)
example. Let's say you have two groups of users, backupteam and
wwwteam, with two different missions. These missions require special
amenagements in various configuration files:

/etc/rc.conf because some services are to be enables
/etc/login.conf because some system-wide limitations are
unsuitable for these missions
/etc/devfs.conf because backupteam should access backup devices
/usr/local/etc/sudoers because some privileges have to be delegated
to users

... and some other random configuration files

You will write two files backupteam.nw and wwwteam.nw where you put
doumentation along with the pieces of /etc/rc.conf you are working on.
You will also nead a system.nw that describes parts of the
configuration unrelated to backupteam nor wwwteam.

After this tou will run noweave on *.nw to produce all configuration
files and notangle on *.nw to produce all documentation files. With
noweb you can pickup almost any documentation format you want, but
plain text is really fine for all the reasons Sylvain Robitaille
mentionned earlier. If you want to give a coool aspect to your plain
text files, I recommand you to try the `fixed' font from Xorg in your
X terminal and in your editor. The fixed font displays cleanly and
it's ``future seen from the 70's'' design is very hype and is in touch
with the contemporary revival of 70's aesthetics.

If you are interested by this way to tackle your configuration files
problem, recall that I do not actually walk this way (for now, this is
just a bluesky idea) and point your favourite web browser to

WWW: http://www.eecs.harvard.edu/~nr/noweb/

You will find gentle tutorials and examples of use.

Being an amateur BSD user, and by no mean a professionnal sysadmin, I
am curious to get the opinion, about this chatting, of experienced
sysadmins that were patient enough to read this very long article.
--
Best wishes,
Michaël

andrea

2007-10-16, 7:22 pm

On 16 Ott, 20:54, michaelgrunew...@yahoo.fr (Micha=EBl Gr=FCnewald) wrote:
> andrea <kerny...@gmail.com> writes:
>
> I am currently thinking about using NOWEB for this purpose. Noweb
> is a literate programming tool. As literate programming is not a very
> common topic, I will give you a taste of it (just in case) before
> discussing how it could be used for your problem.
>
> In case you are not familiar with this kind of tools, literate
> programming tools are designed to produce both a program and its
> documentation from a common source file. Note that the point of view
> is rather different from the one used in tools like DOXYGEN where
> documentation lives as a parasite in program comments.
>
> The most famous literate programming tool is certainly the pair
> CWEAVE, CTANGLE, from a common source CTANGLE will produce a C program
> and CTANGLE a TeX file documenting the program. Unlike CWEAVE/CTANGLE,
> the NOWEB program do not insist producing C programs and TeX-able
> documentation. It is therefore less specialized but more easy to use
> and more adaptable to different tasks.
>
> To give a concrete example of the (hypothetical) usefulness of NOWEB
> is managing administrative files, let's discuss an (hypothetical)
> example. Let's say you have two groups of users, backupteam and
> wwwteam, with two different missions. These missions require special
> amenagements in various configuration files:
>
> /etc/rc.conf because some services are to be enables
> /etc/login.conf because some system-wide limitations are
> unsuitable for these missions
> /etc/devfs.conf because backupteam should access backup devices
> /usr/local/etc/sudoers because some privileges have to be delegated
> to users
>
> ... and some other random configuration files
>
> You will write two files backupteam.nw and wwwteam.nw where you put
> doumentation along with the pieces of /etc/rc.conf you are working on.
> You will also nead a system.nw that describes parts of the
> configuration unrelated to backupteam nor wwwteam.
>
> After this tou will run noweave on *.nw to produce all configuration
> files and notangle on *.nw to produce all documentation files. With
> noweb you can pickup almost any documentation format you want, but
> plain text is really fine for all the reasons Sylvain Robitaille
> mentionned earlier. If you want to give a coool aspect to your plain
> text files, I recommand you to try the `fixed' font from Xorg in your
> X terminal and in your editor. The fixed font displays cleanly and
> it's ``future seen from the 70's'' design is very hype and is in touch
> with the contemporary revival of 70's aesthetics.
>
> If you are interested by this way to tackle your configuration files
> problem, recall that I do not actually walk this way (for now, this is
> just a bluesky idea) and point your favourite web browser to
>
> WWW: http://www.eecs.harvard.edu/~nr/noweb/
>
> You will find gentle tutorials and examples of use.
>
> Being an amateur BSD user, and by no mean a professionnal sysadmin, I
> am curious to get the opinion, about this chatting, of experienced
> sysadmins that were patient enough to read this very long article.
> --
> Best wishes,
> Micha=EBl

Well this project looks really nice, that's what I was looking for,
I'll give it a try.
I know literate programming in haskell, that's very different but the
concept is the same.

Michaël Grünewald

2007-10-16, 7:22 pm

andrea <kerny404@gmail.com> writes:

> On 16 Ott, 20:54, michaelgrunew...@yahoo.fr (Michaël Grünewald) wrote:
>
> Well this project looks really nice, that's what I was looking for,
> I'll give it a try.
> I know literate programming in haskell, that's very different but the
> concept is the same.

My pleasure

--
Cheers,
Michaël

Thorbjoern Ravn Andersen

2007-10-17, 1:34 am

michaelgrunewald@yahoo.fr (Michaël Grünewald) writes:

> Being an amateur BSD user, and by no mean a professionnal sysadmin, I
> am curious to get the opinion, about this chatting, of experienced
> sysadmins that were patient enough to read this very long article.

I have looked into literate programming a long time ago and it is a
fascinating subject but I have since ended up with the opinion that
literate programs are for those implementations that are so complex
that it is impossible to understand without a thorough high level
description - perhaps even with graphs.

When I was a sysadmin I ended up with having a set of predefined
commands to bring the virgin computer correctly on the network and
download an architechture specific tarball of extra scripts which
unpacked in /etc and patched a few existing scripts.

This worked well for us. The differences was clearly documented
(either the result of the bootstrap commands or a file from the
tarball), and comments in the individual files explained why.

These days I write Java - here the refactoring tools are invaluable in
making the code self-explanatory with long descriptive names.

Literate programming is an enlightening exercise which everybody
should try, but I would suggest you try with another project first

--
Thorbjørn Ravn Andersen

andrea

2007-10-17, 7:25 pm

On 17 Ott, 04:34, Thorbjoern Ravn Andersen <nospam0...@gmail.com>
wrote:
> michaelgrunew...@yahoo.fr (Micha=EBl Gr=FCnewald) writes:
>
> I have looked into literate programming a long time ago and it is a
> fascinating subject but I have since ended up with the opinion that
> literate programs are for those implementations that are so complex
> that it is impossible to understand without a thorough high level
> description - perhaps even with graphs.
>
> When I was a sysadmin I ended up with having a set of predefined
> commands to bring the virgin computer correctly on the network and
> download an architechture specific tarball of extra scripts which
> unpacked in /etc and patched a few existing scripts.
>
> This worked well for us. The differences was clearly documented
> (either the result of the bootstrap commands or a file from the
> tarball), and comments in the individual files explained why.
>
> These days I write Java - here the refactoring tools are invaluable in
> making the code self-explanatory with long descriptive names.
>
> Literate programming is an enlightening exercise which everybody
> should try, but I would suggest you try with another project first

> --
> Thorbj=F8rn Ravn Andersen

Yes maybe you're right, comments normally are more than enough.
Anyway I think I may do a simple text file, but the most important
thing is to structure it well, so I can extrapolate data from it.

I also decided to use sshfs, vim it's fine but textmate is much
better ;)

Sylvain Robitaille

2007-10-18, 1:30 am

andrea wrote:

> Yes vim it's fine, I use it for system files, but how do you organize
> the informations?
> Something like that?
> -- 12 OCtober --
> - change 1
> - change 2

Yes, something like that. I use conventions to quickly identify files
that need to be preserved over OS upgrades (for example), or for new
"sections"

A quick example might look something like this:

# ----------------------------------------------------------------------
# 2007/10/17 Sylvain Robitaille (identify who made the change because I
# work on systems with multiple sysadmins; include a brief
# description of the purpose for the change, such as:
# add new DNS resolver)
#
# Note the next line, which identifies a file that should be preserved
# over an OS upgrade:
### /etc/resolv.conf
# --- /etc/old/resolv.conf.20071017 ...
# +++ /etc/resolv.conf
#
# Next lines are a unified context diff of the file that was changed,
# making it easy for a colleague to duplicate the same change on another
# system (for example).
# ----------------------------------------------------------------------
#
# 2007/10/17 Sylvain Robitaille (New section delimitted by the above
# line; if there are commands to issue following the
# modification of a file, for example to restart a process or
# cause it to reload its configuration file, such lines are
# documented as well, without the leading '#' to make it very
# simple for the to be copied and pasted between xterms)
### /etc/syslogd.conf
# --- /etc/old/syslogd.conf.20071017 ...
# +++ /etc/syslogd.conf
#
# (unified context diff of syslogd.conf changes)
kill -HUP `cat /var/run/syslogd.pid`
# ----------------------------------------------------------------------
#
# ...

> I think with latex I could get a much better result, and I don't need
> to write stuff directly on that machine.

Keep it simple to work with, or else you risk not using it as regularly
as you're intending to. You can't get much simpler than a plain-text
file on the system itself.

Also, it makes sense to keep every system's documentation on the systems
themselves (with a sufficient backup strategy, of course), in the same
place on all systems, so you always know where to look to find what's
been changed on any system.

> My question is how to organize informations...

The real answer is "whatever works for you." I hope the above inspires
you to develop a way to organize the information that you find works
even better.

--
----------------------------------------------------------------------
Sylvain Robitaille syl@alcor.concordia.ca

Systems and Network analyst Concordia University
Instructional & Information Technology Montreal, Quebec, Canada
----------------------------------------------------------------------

Thorbjoern Ravn Andersen

2007-10-18, 7:37 am

andrea <kerny404@gmail.com> writes:

> Yes maybe you're right, comments normally are more than enough.
> Anyway I think I may do a simple text file, but the most important
> thing is to structure it well, so I can extrapolate data from it.

If you need to keep data from several machines, then you might as well
start with a spreadsheet - you will end there anyway.

Then save as a CSV and all your scripts parse data from that single
file. This is almost guaranteed to end up saving you time in the long run.

> I also decided to use sshfs, vim it's fine but textmate is much
> better ;)

In the bad old days you ONLY had vi available when you needed to do
emergency rescue, so it was necessary to practice. If you plan on
eventually living from this I'd recommend using the native editor on a
daily basis.

--
Thorbjørn Ravn Andersen

andrea

2007-10-18, 7:37 am

On 18 Ott, 09:24, Thorbjoern Ravn Andersen <nospam0...@gmail.com>
wrote:
> andrea <kerny...@gmail.com> writes:
>
> If you need to keep data from several machines, then you might as well
> start with a spreadsheet - you will end there anyway.
>
> Then save as a CSV and all your scripts parse data from that single
> file. This is almost guaranteed to end up saving you time in the long ru=
n=2E
>
>
> In the bad old days you ONLY had vi available when you needed to do
> emergency rescue, so it was necessary to practice. If you plan on
> eventually living from this I'd recommend using the native editor on a
> daily basis.
>
> --
> Thorbj=F8rn Ravn Andersen

The cvs idea is not bad at all, is there a very light cvs editor for
macosx?
(I don't want to use excel or anything like that of course)

Doug Freyburger

2007-10-18, 1:25 pm

Thorbjoern Ravn Andersen <nospam0...@gmail.com> wrote:
>
> In the bad old days you ONLY had vi available when you needed to do
> emergency rescue, so it was necessary to practice.

I've been in situations where I only had "ed" and occasionally when
all I had was a running "sh" so I was stuck with built-in "echo" and
IO redirection. It is necessary to learn an assortment of basic tools
to fluency, whether practice is needed after that depends on how
good your retention is.

> If you plan on
> eventually living from this I'd recommend using the native editor on a
> daily basis.

SAs need to know vi or vim extremely well. I have forward preferred
various versions of emacs but I actually use vi or vim. It isn't a
matter
or personal preferences. In this sense it is all about practice - As
an
SA I need to be able to edit text files quickly and easily on hosts I
have never logged into before and that likely only have the basics.

Alan Margino

2007-10-18, 1:25 pm

One dull day if ever some lost imp scratched :

> On 16 Ott, 18:33, Sylvain Robitaille <s...@alcor.concordia.ca> wrote:
>
> Yes vim it's fine, I use it for system files, but how do you organize
> the informations?
> Something like that?
> -- 12 OCtober --
> - change 1
> - change 2
>
> I think with latex I could get a much better result,

That's clear but you won't have LaTeX useable on every server you'll have
to admin.

> and I don't need to
> write stuff directly on that machine.

If you don't have the doc local to the machine it's related to
you'll bite your fingers to the bone next time you'll be of
duty on distant access to this poor good old dying server :-)

> My question is how to organize
> informations...

As to organize the info that's beyond the scope od a tool choice,
I guess it is deeply related to your own conditions of work and
your own abilities to synthesize info.
Buildind a doc nest for you and three machines is not on the same
level of anguish and fear than having clear and neat doc for several
rotating teams and hundreds or thousands starving servers in the
world.

Maybe the same question asked on a documentalists newsgroup will
give you the perfect blade but really, as a SA I never believed
there was a magic word that'd fit everyone :-)

I usually recommend to use vi (or 'cat > docfile...^D in case of emerg.)
but you may extend this with frontends and backends like 'asciidoc'
(or similar) wich would empower you of different presentation
abilities like HTML,Xhtml,docbook,pdf,LaTeX exports.
These kind of tools include the "collation of heteregenous docs",
you may export one doc to different export formats one per chapter
or export different docs towards one united doc.
The effort on semantics and rewriting is close to null, basically
you write an ascii text with vi and a few "reflexes" like ``quoting'' words
to quote and *bolding* words to be bold ;-)

Thorbjoern Ravn Andersen

2007-10-18, 7:22 pm

andrea <kerny404@gmail.com> writes:

> The cvs idea is not bad at all, is there a very light cvs editor for
> macosx?

You could just use tab-separated lines in any editor.
--
Thorbjørn Ravn Andersen

Dave Hinz

2007-10-18, 7:22 pm

On Thu, 18 Oct 2007 09:04:05 -0700, Doug Freyburger <dfreybur@yahoo.com> wrote:
> Thorbjoern Ravn Andersen <nospam0...@gmail.com> wrote:
>
> I've been in situations where I only had "ed" and occasionally when
> all I had was a running "sh" so I was stuck with built-in "echo" and
> IO redirection. It is necessary to learn an assortment of basic tools
> to fluency, whether practice is needed after that depends on how
> good your retention is.

Yup. Back in the dark ages, I once rebuilt the hosts file on our NIS
master with:
cat > /etc/hosts
....and a bit of luck remembering enough IPs to let the box know who it
was and who it could get the real hosts file from.

Fun interview question: you have physical access to the box but its
network is gone, and you have no root shell. How do you get it back
online?

Thorbjoern Ravn Andersen

2007-10-19, 1:33 am

Dave Hinz <DaveHinz@gmail.com> writes:

> Fun interview question: you have physical access to the box but its
> network is gone, and you have no root shell. How do you get it back
> online?

Insufficient data.

Unplug and replug the network cable?

--
Thorbjørn Ravn Andersen

Doug Freyburger

2007-10-19, 1:32 pm

Dave Hinz <DaveH...@gmail.com> wrote:
> Doug Freyburger <dfrey...@yahoo.com> wrote:
>
>
>
> Yup. Back in the dark ages, I once rebuilt the hosts file on our NIS
> master with:
> cat > /etc/hosts
> ...and a bit of luck remembering enough IPs to let the box know who it
> was and who it could get the real hosts file from.

BTDTgtTS. I've also done the same with /etc/passwd to a 1-liner
and later gone back to recover it from backup tape.

> Fun interview question: you have physical access to the box but its
> network is gone, and you have no root shell. How do you get it back
> online?

Huh. You've managed to overhear one of my interviews a few
years ago? Scenario questions are the most rewarding to both
ask and answer.

Dave Hinz

2007-10-19, 7:20 pm

On 19 Oct 2007 06:25:44 +0200, Thorbjoern Ravn Andersen <nospam0000@gmail.com> wrote:
> Dave Hinz <DaveHinz@gmail.com> writes:
>
[vbcol=seagreen]
> Insufficient data.

Best kind of interview question. Can't just hand 'em the answer, I want
to see how they think.

> Unplug and replug the network cable?

Didn't work.

Sylvain Robitaille

2007-10-20, 1:31 am

Dave Hinz wrote:

>
> Didn't work.

Any log messages on the console to give the interviewee a hint at the
problem?

--
----------------------------------------------------------------------
Sylvain Robitaille syl@alcor.concordia.ca

Systems and Network analyst Concordia University
Instructional & Information Technology Montreal, Quebec, Canada
----------------------------------------------------------------------

Dave Hinz

2007-10-20, 1:22 pm

On Sat, 20 Oct 2007 03:42:18 +0000 (UTC), Sylvain Robitaille <syl@alcor.concordia.ca> wrote:
> Dave Hinz wrote:
>
>
> Any log messages on the console to give the interviewee a hint at the
> problem?

Neither of them seemed to notice the cable being removed or replaced.
And yup, it's one of those "doesn't matter what specific approach you
use, just show me how you think" kind of questions.

Thorbjoern Ravn Andersen

2007-10-21, 7:31 am

Dave Hinz <DaveHinz@gmail.com> writes:

>
> Best kind of interview question. Can't just hand 'em the answer, I want
> to see how they think.

>
> Didn't work.

Ask boss who HAS root shell, and get their number.
--
Thorbjørn Ravn Andersen

edcrosbys

2007-10-22, 1:27 pm

I'll give it a shake..

Situation:
Server doesn't have network connectivity and I cannot get root access.

Assumptions:
no root console access due to incorrect passwd
something is running that will be corrupted if we bounce and force our
way in via single user.
domainname was mentioned sounds like sweet sweet insecurity to me.
The co-workers can provide little assistance (in the way of user level
acct only)

Query users/bosses/others for any admin type access - probably futile,
but could pay off
Hop on a functioning box as user and grab NIS map. Run NIS map (edited
for user security, of course) through jack the ripper.
While Jack is running, hop on dead box as user.
Look at network config, log files, GSM hardware logs, sudo config
(pray some more), others with uid 0, are there apps that prevent
forced access.
Have network guy check things from his end just in case.
If everything appears to be configured correctly and you see no
errors, replace the cable.
Check for SUID/SGID files

If everything is properly secured (except using NIS) and the issue is
a config/hardware problem on the server, then you will need to bring
the box down to gain access and/or fix hardware. Now if my assumptions
were off, you have a different ball game.

Thank you, I enjoyed the exercise

Dave Hinz

2007-10-24, 1:31 am

On Mon, 22 Oct 2007 12:48:11 -0000, edcrosbys <edcrosbys@gmail.com> wrote:
> I'll give it a shake..
> Situation:
> Server doesn't have network connectivity and I cannot get root access.

A vague situation description, I'll admit, yes.

> Assumptions:
> no root console access due to incorrect passwd
> something is running that will be corrupted if we bounce and force our
> way in via single user.

oooh, a nice twist, thank you; I may use that.

> domainname was mentioned sounds like sweet sweet insecurity to me.

Oh, hell yes.

> The co-workers can provide little assistance (in the way of user level
> acct only)
> Query users/bosses/others for any admin type access - probably futile,
> but could pay off

Nice approach.

> Hop on a functioning box as user and grab NIS map. Run NIS map (edited
> for user security, of course) through jack the ripper.
> While Jack is running, hop on dead box as user.
> Look at network config, log files, GSM hardware logs, sudo config
> (pray some more), others with uid 0, are there apps that prevent
> forced access.

In other words, bad security practices are out there, see if any of 'em
are in place here you can exploit. Hell, if we had NIS, we could create
a (mumble) with a UID of (grumblesnarf) and be in.

> Have network guy check things from his end just in case.
> If everything appears to be configured correctly and you see no
> errors, replace the cable.

Stranger things have happened.

> Check for SUID/SGID files
> If everything is properly secured (except using NIS) and the issue is
> a config/hardware problem on the server, then you will need to bring
> the box down to gain access and/or fix hardware. Now if my assumptions
> were off, you have a different ball game.

> Thank you, I enjoyed the exercise

You gave me a couple ideas that I haven't used. If the box is off the
network and deemed dead enough to call dead, options then include trying
to boot from alternate media (cd, boot net:dhcp - s , or probably other
ways), or the ultimate brute force, take the HD out and stick it in a
box you HAVE root on.

With physical access, logical access is just a matter of time. The most
fascinating thing I ever watched was one of the guys who at the time
worked for me, break into a box by dropping to the OK prompt and poking
around in the memory, changing the effective UID of the running process
to 0, and then typing "go" at the OK prompt to get back into his (now,
root) shell. Amazing.

Frank Cusack

2007-10-24, 7:31 am

User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (darwin)
Cancel-Lock: sha1:inOpiXgE8LUdDOZUENrwOKQLTqU=
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Complaints-To: abuse@supernews.com
Lines: 9
Bytes: 1705
X-Original-Bytes: 1662
Xref: number1.nntp.dca.giganews.com comp.unix.admin:123966

On 24 Oct 2007 03:47:01 GMT Dave Hinz <DaveHinz@gmail.com> wrote:
> With physical access, logical access is just a matter of time. The most
> fascinating thing I ever watched was one of the guys who at the time
> worked for me, break into a box by dropping to the OK prompt and poking
> around in the memory, changing the effective UID of the running process
> to 0, and then typing "go" at the OK prompt to get back into his (now,
> root) shell. Amazing.

cool. i've heard of that, never seen it.

jpd

2007-11-09, 1:23 pm

Begin <pan.2007.10.18.16.30.44@connorthinknor.com>
On 18 Oct 2007 16:30:46 GMT, Alan Margino <rm-rf@connorthinknor.com> wrote:
> One dull day if ever some lost imp scratched :

Personally I like nvi better, as vim's undo behaviour drives me up the
wall within minutes, but anyhow. Let's assume there will be some editor.

[vbcol=seagreen]
>
> That's clear but you won't have LaTeX useable on every server you'll have
> to admin.

Allow me to point to troff instead. It's used for manpages, and altough
it's not the fanciest there is (lore has it its limitations caused TeX),
it certainly is usable for documentation like this. In fact, the mere
presence of nroff makes it an excellent idea.

My own macroset I use for letters is minimalist and still looks nice;
I imagine something similar can be done for site docs and it'll be of
similar size: a few pages. Or do the even more obvious and use the man
macroset.

For storing the various versions CVS or even RCS might be useful. Many
unices come with it anyway or you could put it on a designated metabox.

I have to admit I had trouble getting my head around it at first. Get
a book like _Unix Text Processing_[1] to get started. It helped me.

>
> If you don't have the doc local to the machine it's related to
> you'll bite your fingers to the bone next time you'll be of
> duty on distant access to this poor good old dying server :-)

A bit of Makefile magic, maybe rsync or packing up the pages in your
preferred packaging system and /streaming/ them with the usual updates
might be a solution. You might even introduce dependencies to make sure
the docs stay in sync, altough it might not work for everything.

>
> As to organize the info that's beyond the scope od a tool choice,
> I guess it is deeply related to your own conditions of work and
> your own abilities to synthesize info.
> Buildind a doc nest for you and three machines is not on the same
> level of anguish and fear than having clear and neat doc for several
> rotating teams and hundreds or thousands starving servers in the
> world.

The most important thing IME is to get started and get through
everyone's heads that keeping docs up-to-date is Useful[tm].

Where the tools are important the getting people to use them is an
obvious people problem, ie, requires management. So you manage yourself;
it's still management and deserves attention from that angle. Competent
attention, of course, and we all know it's scarce, but that's besides
this argument.

> Maybe the same question asked on a documentalists newsgroup will
> give you the perfect blade but really, as a SA I never believed
> there was a magic word that'd fit everyone :-)

That's true enough. So it's a good idea to identify the requirements
of this situation. In general...

At WeMakeSoftware I used to work for, a development project leader with
half an administration clue deployed a wiki, then encouraged everybody
to write into it. That sorta worked, at least better than trying to
get people to write stuff then try to gather it somewhere.

It also showed not everybody can write for other people even in their
own field. That is to be expected, of course, but I'll take the
opportunity to point out that having someone go over the collected works
regularly and edit it for readability is useful. Fred Brooks argues in
_the mythical man-month_ that you need to have a designated editor or
two, but no more, for a technical body of work. He said it in context of
capturing all the details pertaining to designing hardware and software
systems, but I don't see that much difference with this case.

My point? You can do it formally or informally, but your documentation
needs to be maintained. Stating the bleeding obvious is something a SA
does more often than he cares for, but it seems to be necessairy. I
don't necessairily mean that in any negative way.

> I usually recommend to use vi (or 'cat > docfile...^D in case of emerg.)
> but you may extend this with frontends and backends like 'asciidoc'
> (or similar) wich would empower you of different presentation
> abilities like HTML,Xhtml,docbook,pdf,LaTeX exports.
> These kind of tools include the "collation of heteregenous docs",
> you may export one doc to different export formats one per chapter
> or export different docs towards one united doc.

That's a pretty neat feature... in theory. In the UNIX SA sitedocs case,
most text is either plain text config files or whatever markup the SA
team thought cool to standardize on. Anything else should've been munged
into the preferred format long ago... with a small shell script.

> The effort on semantics and rewriting is close to null, basically
> you write an ascii text with vi and a few "reflexes" like ``quoting'' words
> to quote and *bolding* words to be bold ;-)

As a sidenote, markup is mostly a non-issue. Even good old troff works
reasonable, and looks pretty nice on paper as well as on a terminal.
Latex works. Heck, I hacked my own markup to feed to an awk script that
generates html or (another script that generates) css and that works
pretty well too. I possibly could've used m4 if I didn't hate it.

Also, I'm still working on finding the resources to take some wiki with
a halfway reasonable markup and adding a troff generating backend next
to the html backend. That gets you manpages and postscript, and that
opens the door to pdfs and paper versions. And so on. I'm open for
suggestions on this both here and in email.

[1] I seem to plug this far too often. It's available On The Web for
free now, and an excellent read for beginner and intermediate unix
text tool user alike--even if some info is a bit dated now.

--
j p d (at) d s b (dot) t u d e l f t (dot) n l .
This message was originally posted on Usenet in plain text.
Any other representation, additions, or changes do not have my
consent and may be a violation of international copyright law.

Bill Vermillion

2007-11-09, 1:23 pm

In article <slrnfj98iu.1u34.read_the_sig@mantell0.local>,
jpd <read_the_sig@do.not.spam.it.invalid> wrote:
>Begin <pan.2007.10.18.16.30.44@connorthinknor.com>
>On 18 Oct 2007 16:30:46 GMT, Alan Margino <rm-rf@connorthinknor.com> wrote:
>
>Personally I like nvi better, as vim's undo behaviour drives me up the
>wall within minutes, but anyhow. Let's assume there will be some editor.
>
>
[vbcol=seagreen]
>Allow me to point to troff instead. It's used for manpages,
>and altough it's not the fanciest there is (lore has it its
>limitations caused TeX), it certainly is usable for documentation
>like this. In fact, the mere presence of nroff makes it an
>excellent idea.

>My own macroset I use for letters is minimalist and still looks nice;
>I imagine something similar can be done for site docs and it'll be of
>similar size: a few pages. Or do the even more obvious and use the man
>macroset.

>For storing the various versions CVS or even RCS might be useful. Many
>unices come with it anyway or you could put it on a designated metabox.

My first 'experience' with RCS was truly by accident and I thought
I had lost the file I was working on - but a search found it.

I meant to edit a file with 'vi' but my finger slipped and
I type 'ci' by accident :-( and/or :-). That had to be about
20 years ago.

Bill
--
Bill Vermillion - bv @ wjv . com

Dave Hinz

2007-11-10, 1:33 am

On Fri, 09 Nov 2007 19:28:41 -0500, Tim Stewart <tstewart@ciena.com> wrote:
> Hello everyone,
>
> Dave Hinz <DaveHinz@gmail.com> writes:
>
>
> I missed the `domainname' post and can't seem to load it in my
> newsreader. I'm curious what the sweet sweet insecurity is. I can
> imagine several possibilities--please enlighten me.

Well, sometimes implies NIS which has a few ... opportunities.

>
> WOW. That's Awesome.

Oh yeah, he's _that_ good.

> Now you've motivated me to go learn the hacking features of the ok
> prompt. What a great way to show off to your nerd buddies.

Now you make it go and sound like a parlor trick. ;)

Tim Stewart

2007-11-10, 1:33 am

Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: tomate.motzarella.org U2FsdGVkX1+24FCr6y9S3xWE4sbzVS2ZYcZxx4Ff
osKjnMCUz093rFCR0mktMc/ 6s4DZjPuHY0iA18FEPReml6Ix9WzRuaOxXfV91DQ
rB+xjar5Q+cY6EkD+iGCHBNIT6YN/AInuP3125CYgTm4vNw==
X-Complaints-To: Please send complaints to abuse@motzarella.org with full headers
NNTP-Posting-Date: Sat, 10 Nov 2007 00:29:03 +0000 (UTC)
Cc: Steve Ayotte <sayotte@ciena.com>
X-Auth-Sender: U2FsdGVkX1/ J2z1A8EaSpMPFcPCK61i6f0G0ZIbyMdmzoxrBHmV
7cQ==
Cancel-Lock: sha1:8RjXeM76AXZb/JDoaIv4p2z3x2k=
sha1:hxr+5LuDbAz0LFdDAlBHpys1oe0=
User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1 (gnu/linux)
Bytes: 2565
Xref: number1.nntp.dca.giganews.com comp.unix.admin:124060

Hello everyone,

Dave Hinz <DaveHinz@gmail.com> writes:

>
> Oh, hell yes.

I missed the `domainname' post and can't seem to load it in my
newsreader. I'm curious what the sweet sweet insecurity is. I can
imagine several possibilities--please enlighten me.

> With physical access, logical access is just a matter of time. The
> most fascinating thing I ever watched was one of the guys who at the
> time worked for me, break into a box by dropping to the OK prompt
> and poking around in the memory, changing the effective UID of the
> running process to 0, and then typing "go" at the OK prompt to get
> back into his (now, root) shell. Amazing.

WOW. That's Awesome.

Now you've motivated me to go learn the hacking features of the ok
prompt. What a great way to show off to your nerd buddies.

--
-TimS

Tim Stewart
Lead UNIX Systems Administrator
Ciena Corporation
Alpharetta, GA, USA
tstewart@ciena.com

Tim Stewart

2007-11-10, 1:33 am

Dave Hinz <DaveHinz@gmail.com> writes:
>
> Well, sometimes implies NIS which has a few ... opportunities.

That was my first thought. Not having control of the NIS server, but
being able to change the domainname... sounds like fun.

>
> Oh yeah, he's _that_ good.

I'm still thinking about the awesome.

>
> Now you make it go and sound like a parlor trick. ;)

Haha, no, that's not what I meant at all. That is quite advanced
wizardry.

However, it is just the sort of thing I like to play with. About a
year ago I took it upon myself to use mdb on SunOS 5.9 to reduce the
minimum unprivileged port number down to 125 to show someone that it
could be done but wasn't a good idea at all. This isn't near as cool
as using the ok prompt to change a process' UID, however, which leads
to my desire to try it.

Evil Hacks are one of my favorite things

--
-TimS

Tim Stewart
Lead UNIX Systems Administrator
Ciena Corporation
Alpharetta, GA, USA
tstewart@ciena.com