SourceFiles.org - Use the Source, Luke

<HTML>

<HEAD><TITLE>Petal FAQ/README</TITLE></HEAD>

<H4>What is Petal?</H4>

The short answer: think of a mix of Unix's <TT>chmod</TT> and <TT>chown</TT>, but with a memory.

A slightly longer version: Petal maintains permissions on a set of files by recalling that information from a data store. You may create a data store by hand, or let Petal generate one for you based on a tree's existing permissions.

<H4>Under what operating systems will Petal build?</H4>

See the <TT>INSTALL</TT> file, included in the source distribution, for details. The short version is that Petal should build under just about any Unix-like operating system that has:

<UL>

<LI>

        <B>a recent C++ compiler,</B>
        one that supports STL and exceptions
        </P>

<LI>

        <B>a recent version of
        <A HREF="ftp://ftp.rpm.org/pub/rpm/dist">popt</A>
        </B>
        </P>

<LI>

        <B>GNU Flex and Bison.</B>  Many systems install Flex and Bison
        under the names <TT>lex</TT> and <TT>yacc</TT> because they are
        backward-compatible with their older counterparts; but plain old
        lex and yacc will <EM>not</EM> work.
        </P>

</UL>

If these requirements are met, try the age-old <TT>configure ; make ; make install</TT> routine. That's it.

INSTALL</TT> file for details. I have personally built Petal under RedHat Linux 9 and Solaris 8, both with a 3.x-release GCC. I expect it to build under a number of other OS's, though, so please let me know if doing that works for you.

<H4>What's Petal's license?</H4>

See the <TT>LICENSE</TT> file, included with the source code distribution, for details. The short and unofficial version boils down to:

<UL>

<LI> 
Petal comes with no warranty whatsoever, use at your own risk;</LI>

<LI> 
please give credit where credit is due: if you create a derived work, be sure to tell people from where you derived it; and</LI>

<LI> 
if you create a derived work, it cannot include the name "petal" without explicit written permission from me, Petal's author</LI>

</UL>

<H4>Does Petal come with any sort of warranty?</H4>

Petal comes with NO WARRANTY WHATSOEVER. I make ABSOLUTELY NO CLAIMS that Petal is suitable for any purpose.

Caveat emptor.

<H4>So, then, Petal is designed to destroy my files?</H4>

No, it is not.

Aside from its configuration files, Petal does not alter a file's data; it alters its permissions.

Problems with permissions changes can be just as troublesome to resolve, true; but Petal's purpose is to prevent that sort of mishap by resetting permissions to a specified, known state.

<H4>Why do you misuse the terms "perms" and "permissions?" Permissions are set by chmod, while ownership is set by chown.</H4>

I use the term "perms" to reflect the entire set of access rights to a file: owner and group in addition to the numeric mode. Think of it as shorthand for "owner/group/mode."

<H4>Why the name Petal?</H4>

A "root/branch/leaf" analogy is often used to describe Unix-style filesystems. Petal is something of a filesystem maintenance tool. I didn't like any of the names based on the term "leaf," though, so I went for another leaf-like analogy: a flower petal.

True to old-school Unix form, I also wanted a short name, one relatively easy to type.

<H4>What was the motivation behind Petal?</H4>

Unix <TT>chown/chmod</TT> fall on the extremes -- either too narrow [single file] or too broad [recursive, all the same perms]. For the most part this is not a problem; but I found myself in situations where I was writing some very detailed scripts to keep a tree's files properly permissioned.

For example: I'd implemented a nameserver system using CVS to track changes to the zone files. Admins would checkout/update/checkin the zone files, then run a script via sudo to populate the live content and kick the name daemon. Part of the script involved multiple messy chmod and chown calls to get the file perms "just right" to satisfy security concerns: files readable, not writable, to members of a given group; directories not writable by the name daemon user; and so on.

Sure, we weren't using CVS for its intended purpose -- a source code control system shouldn't have to worry about setting perms and the like, since part of that's traditionally done by the compiler [creating executable files] -- but it was a pain nonetheless. Soon after I realized there were many areas of systems adminstration that could benefit from a tool that provided precision perms assignment, and drafted plans for Petal's implementation. The rest is history.

<H4>I see the word "data store" and "config file" used interchangeably in some of the source code and documentation; why is this?</H4>

One of Petal's design goals was extendability. By default it uses a custom flat file format to store file info; but the code is written such that Petal could be extended to read data from any number of sources, e.g. DBM, or XML, using a plugin architecture.

As of version 0.70.0, Petal supports a plugin for PostgreSQL v7.x databases. (This requires, of course, access to a working <A HREF="http://www.postgresql.org">PostgreSQL v7.x database</A>.) By using a centralized, remote data store, administrators now have greater ease of maintenance when using Petal for cloned/farmed machines, among other uses...

Please note, the plugin architecture is experimental right now, and only works under OS's that support the <TT>dlopen()/dlsym()/dlclose()</TT> family of functions (aka Linux and Solaris). See the file <TT>README_PLUGINS</TT>, in the source distribution, for details.

<H4>What are some uses of Petal?</H4>

Besides the obvious "set perms on specified files," this could be extended to:

<UL>
<LI> 
automated package installs or machine builds. After a JumpStart/KickStart/Ignite, a script could pull system config files from a central repository and run Petal to set their perms accordingly.</LI>

<LI> 
any place where source code control is used for non-source files, e.g. system config files or DNS zone files. In both cases, files could be checked out of source control by nonroot users, and after checkin, root could pull the files out of source control [into their proper locations] and run Petal to reinstate any fine-grained perms. [In turn, this mythical script could be run via sudo.]</LI>

<LI> 
regular "resets" of permissions on large trees of shared files. For example, a large-scale website may require occasional tweaks after content has been distributed. Use of Petal via cron solves the problems that occur when a user's default (read: tight) umask sneaks into files that should be publicly viewable.</LI>

</UL>

<H4>I saw the word "sudo" back there. Is it safe to use Petal via sudo?</H4>

This is more of a sudo question, really; but since I've used sudo quite a bit, here's some general guidance:

Use common sense when running sudo. It gives nonroot users temporary root access. If you provide an opening (through a poorly-crafted sudo-run commandline) for someone to grant themselves permanent root access, well, then you have some cleanup on your hands.

Back to the specific: Petal is essentially a precision <TT>chown/chmod</TT>, so don't put people in a position to modify access to files they shouldn't. For example, if you let your users run Petal via sudo, do not grant them write-access to the data store.

<H4>That describes what I can do to make use of Petal more secure for my site; what steps does Petal take internally to prevent misuse?</H4>

<OL>
<LI> 
Petal does not follow symbolic links. Perhaps, someday, there will be a means to override this behavior with a commandline switch; but for the time being Petal uses only <TT>lstat()</TT> and <TT>lchown()</TT> when operating on target files, not <TT>stat()</TT> and <TT>chown()</TT>.</LI>

<LI> 
When possible, Petal uses C++ strings instead of char pointers when processing user input. This discourages buffer overflows.
</LI>

<LI> 
Petal checks itself on startup and refuses to run if it is setuid or setgid. If Petal is not setuid/setgid, then malicious people cannot coerce it into providing them any priveleges they do not already have -- i.e. even if they are able to cause a buffer overflow and execute arbitrary code, this is done as the process's real uid which is... themself. No harm here, just a coredump.</LI> </OL>

Beyond this, Petal is just <TT>chown()/chmod()</TT> with a memory.

<H4>Should I run Petal setuid/setgid root?</H4>

Running Petal setuid/setgid is not only strongly discouraged, it is not possible unless you hack the source code [and, in that case, you're on your own].

You know your site better than I do, but my experience has demonstrated that there are few cases [roughly 0] in which this would be a benefit.

Perhaps, someday, I will add a flag to
<TT>configure</TT> such that this behavior may be disabled at compile-time.

<H4>Does this mean Petal is invulnerable?</H4>

Of course not.

Like most software, Petal was not hand-coded from raw <TT>0</TT>'s and <TT>1</TT>'s but instead relies on some backend tools and langauges to make it work. These tools are mentioned in the <TT>INSTALL</TT> document, and include:

<UL>

<LI> 
C++ and the STL

<LI> 
GNU Flex and Bison, for parsing flat-text data stores

<LI> 
libpopt, for processing command-line arguments

</UL>

If vulnerabilities are found in any of the above-mentioned tools, Petal MAY have inherited the bug. At that point, you would have to try to reproduce the bug and see whether you hit the jackpot.

Before you panic, though, consider the following:

<CENTER>How are you using Petal?</CENTER>

In other words:

<UL>
<LI> 
Petal isn't a daemon/listener, so it's not susceptible to random network probes.

<LI> 
Petal cannot grant people ownership of files they do not already own, unless it is run setuid root -- and unless you've hacked the source code, Petal refuses to run if it detects it is setuid/setgid.

<LI> 
It is strongly advised that Petal NOT be run setuid/setgid -- i.e. that you don't hack the source -- so any sort of stack-smashing shouldn't give anyone any priveleges they do not already have.

</UL>

With that in mind, the avenues of misusing Petal are very much limited.

End of Petal FAQ/ReadMe.

</BODY>
</HTML>