summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorMichael DeHaan <mdehaan@redhat.com>2008-02-07 12:08:55 -0500
committerMichael DeHaan <mdehaan@redhat.com>2008-02-07 12:08:55 -0500
commit697402da24ca930b3608359a61b9872fdddc62d9 (patch)
tree625403025dbfe9caca1254aab45724c8de4d8302 /docs
parentac3061bcffd2ea634596c188beaa13339e3fa24a (diff)
downloadcertmaster-697402da24ca930b3608359a61b9872fdddc62d9.zip
certmaster-697402da24ca930b3608359a61b9872fdddc62d9.tar.gz
certmaster-697402da24ca930b3608359a61b9872fdddc62d9.tar.xz
Starting off the certmaster tree with most of the func code, shortly non-certmaster related parts will be removed, and other small parts added/tweaked
Diffstat (limited to 'docs')
-rw-r--r--docs/.gitignore2
-rwxr-xr-xdocs/Makefile7
-rw-r--r--docs/certmaster-ca.pod41
-rw-r--r--docs/certmaster.pod29
-rw-r--r--docs/func-inventory.pod70
-rw-r--r--docs/func.pod111
-rw-r--r--docs/funcd.pod25
7 files changed, 285 insertions, 0 deletions
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..46952a3
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,2 @@
+# ignore compressed man pages
+*.gz
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100755
index 0000000..ede53b5
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,7 @@
+
+
+clean::
+ @rm -fv *.pyc *~ .*~ *.pyo
+ @find . -name .\#\* -exec rm -fv {} \;
+ @rm -fv *.rpm
+ @rm -fv *.gz
diff --git a/docs/certmaster-ca.pod b/docs/certmaster-ca.pod
new file mode 100644
index 0000000..fce3f73
--- /dev/null
+++ b/docs/certmaster-ca.pod
@@ -0,0 +1,41 @@
+=head1 NAME
+
+certmaster-ca -- signs certificate requests gathered by certmaster.
+
+=head1 SYNOPSIS
+
+certmaster-ca --list
+
+certmaster-ca --sign machine.example.org
+
+=head1 DESCRIPTION
+
+"certmaster-ca --list"
+
+The list command prints all certificates that have been requested from certmaster by a remote
+service (such as funcd) but are not yet signed.
+
+func commands can't be sent to a remote machine until the certificates have been signed.
+
+"certmaster-ca --sign [hostname]"
+
+This command is used to sign a certificate and send it back to the requester.
+
+=head1 AUTO-SIGNING
+
+The certmaster can be configured to make this command unneccessary; all incoming
+requests can be signed automatically by certmaster.
+
+To configure this, edit /etc/func/certmaster.conf.
+
+=head1 ADDITONAL RESOURCES
+
+See https://hosted.fedoraproject.org/projects/func/. It's a Wiki.
+
+See also the manpages for "func", "func-inventory", "funcd", and "certmaster".
+
+=head1 AUTHOR
+
+Various. See https://hosted.fedoraproject.org/projects/func
+
+
diff --git a/docs/certmaster.pod b/docs/certmaster.pod
new file mode 100644
index 0000000..92f5074
--- /dev/null
+++ b/docs/certmaster.pod
@@ -0,0 +1,29 @@
+=head1 NAME
+
+certmaster -- hands out certificates to funcd and other components.
+
+=head1 SYNOPSIS
+
+certmaster (it's a daemon and takes no arguments)
+
+=head1 DESCRIPTION
+
+See https://hosted.fedoraproject.org/projects/func/
+
+Certmaster is run on the master-control machine on a network being
+controlled by func. It hands out certificates to machines running
+funcd.
+
+Certmaster is configured by /etc/func/certmaster.conf
+
+=head1 ADDITONAL RESOURCES
+
+See https://hosted.fedoraproject.org/projects/func/. It's a Wiki.
+
+See also the manpages for "func", "func-inventory", "funcd", "certmaster-ca".
+
+=head1 AUTHOR
+
+Various. See https://hosted.fedoraproject.org/projects/func
+
+
diff --git a/docs/func-inventory.pod b/docs/func-inventory.pod
new file mode 100644
index 0000000..cfe362d
--- /dev/null
+++ b/docs/func-inventory.pod
@@ -0,0 +1,70 @@
+=head1 NAME
+
+func-inventory -- Takes inventory of data from func minions, and stores them in git.
+
+=head1 SYNOPSIS
+
+func-inventory [--verbose] [--server-spec glob] [--methods list] [--modules list] [--tree path] [--no-git]
+
+=head1 DESCRIPTION
+
+func-inventory runs against func-minions to gather information, and stores this information on the filesystem, in a tree arranged by hostname, module name, and method name.
+
+After each update, differences are commited to version control (using git), where they can be examined with tools such as "git log" and "gitk".
+
+=head1 --verbose
+
+Provides extra output about what func-inventory is doing.
+
+=head1 --server-spec
+
+A glob, as can be given to "func", that describes what machines the inventory program should run against. The default is "*".
+
+=head1 --modules list
+
+A comma-seperated list of modules that should be included in the inventory, for instance "hardware,packages".
+The default is "all".
+
+=head1 --methods list
+
+A comma-seperated list of methods that should be included in the inventory, for each module being queried. The default
+is "info", which saves the data for any module that has an "info" method.
+
+=head1 --tree-path
+
+Selects the location where func-inventory will output data. The default is /var/lib/func/inventory. This directory will
+contain a tree structure based on the hostnames, modules, and methods included in the inventory.
+
+=head1 --no-git
+
+Disables git integration, meaning changes will not be tracked using version control. This option is present
+for those that do not have the "git-core" package installed, though installing it is highly recommended to get
+the full degree of power out of func-inventory.
+
+=head1 VIEWING CHANGES
+
+Since func-inventory integrates with git, all changes to the remote systems (including additions of new systems) can
+be tracked using standard git-tools such as "git log" and "gitk", when run on the directory specified for --tree.
+
+Additional built in hooks to notify changes can be written using git's own trigger mechanism, though something
+more specific to func will likely be developed in the future -- also eliminating the need to grok git internals.
+
+=head1 ALTERNATIVE OUTPUT FORMATS
+
+func-inventory can be passed a --json or --xmlrpc parameter to override the default output format. These
+output formats are much less readable in the git-produced diffs, but are more easily loaded by other programs
+that may want to "mine" the output of a func-inventory tree. Using --json requires that the python-simplejson
+RPM be installed.
+
+=head1 ADDITONAL RESOURCES
+
+See https://hosted.fedoraproject.org/projects/func/ for more information.
+
+See also the manpages for "func", "funcd", "certmaster", and "certmaster-ca".
+
+=head1 AUTHOR
+
+Michael DeHaan <mdehaan@redhat.com>
+
+
+
diff --git a/docs/func.pod b/docs/func.pod
new file mode 100644
index 0000000..5ee594b
--- /dev/null
+++ b/docs/func.pod
@@ -0,0 +1,111 @@
+=head1 NAME
+
+Func -- Fedora Unified Network Controller.
+
+=head1 SYNOPSIS
+
+func "*" list_minions
+
+func target.example.org call module method [args ...]
+
+func "target*.example.org" call module method [args ...]
+
+func "webserver1;mailserver2" call module method [args ...]
+
+=head1 DESCRIPTION
+
+"func" allows remote control of machines running funcd (called "minions")
+that are set to obey this machine (called the "overlord"). This includes
+performing various remote operations and gathering data.
+
+"func" can address multiple machines at the same time by specifying
+their names with globs, which follow shell glob syntax.
+
+See the project homepage (below) for a list of modules available
+and a more in-depth description of what each of them do.
+
+=head1 THE "CALL" MODULE
+
+The "call" module is used for running func modules remotely.
+
+Format: func "*.example.org" call <module> <function> [ args ... ]
+
+=head1 LISTING REMOTE MODULES AVAILABLE
+
+It's possible to ask func minions what modules they have installed:
+
+func "*.example.org" call system list_modules
+
+=head1 LISTING REMOTE FUNCTIONS AVAILABLE IN A MODULE
+
+It is also possible to ask remote func modules what functions they support:
+
+func target.example.org call modulename list_methods
+
+=head1 CALLING A REMOTE COMMAND
+
+Once you have the name of a module you want to run, use call to invoke it:
+
+func target.example.org call modulename methodname
+
+=head1 OUTPUT FORMATS
+
+The "call" command by default outputs data using a "pretty printer". Other
+display options include --raw, --json, and --xmlrpc, which may be more
+desirable if you are running func inside another script or prefer to read
+those display formats.
+
+Example: func "*" call --json service inventory
+
+
+=head1 HELPER MODULES
+
+In addition to "call", there are other modules that make control of remote
+machines, as well as data display, more user friendly. They augment "call"
+by providing some additional functionality.
+
+You will notice that the syntax for using one of these helper modules
+varies slightly from just using "call" directly.
+
+For example "show" can be used to show remote data. The normal command "func '*'
+command would dump a very large amount of data, while the show command can mine
+only a few details. This might make things more readable, for instance, when
+not going through the Python API (where you would not care).
+
+func "*.example.org" show hardware --help
+
+func "*.example.org" show hardware systemMemory
+
+func "*.example.org" show hardware os
+
+Another useful helper command module is copyfile, which allows func to work like scp from
+the shell, though it can address multiple systems at the same time.
+
+The following example pushes one file out to multiple systems:
+
+func "*.example.org" copyfile --file=/tmp/foo --remotepath=/tmp/foo
+
+While these helper modules will grow over time, usage of "call" syntax
+directly is fine also. See the Wiki for more examples as they evolve.
+
+=head1 --verbose
+
+Use this flag to output extra information from func while it is running.
+All func commands can take this flag.
+
+=head1 EXIT_STATUS
+
+Func commands have return values that vary based on the module being
+called. See the project page (linked below) for more information.
+
+=head1 ADDITONAL RESOURCES
+
+See https://hosted.fedoraproject.org/projects/func/ for more information, including information on scripting func from Python.
+
+See also the manpages for "func-inventory", "funcd", "certmaster", and "certmaster-ca".
+
+=head1 AUTHOR
+
+Various. See https://hosted.fedoraproject.org/projects/func
+
+
diff --git a/docs/funcd.pod b/docs/funcd.pod
new file mode 100644
index 0000000..da4ec75
--- /dev/null
+++ b/docs/funcd.pod
@@ -0,0 +1,25 @@
+=head1 NAME
+
+funcd -- deaemon for the Fedora Universal Network Controller
+
+=head1 SYNOPSIS
+
+funcd (it's a daemon and takes no arguments)
+
+=head1 DESCRIPTION
+
+funcd registers itself to a certificate server (certmaster) listed in /etc/func/minion.conf and takes orders from the command line func when that program is run from that certificate server. See /etc/func/minion.conf for other configuration options.
+
+Modules and capabilities provided by funcd are specified at https://hosted.fedoraproject.org/projects/func/
+
+=head1 ADDITONAL RESOURCES
+
+See https://hosted.fedoraproject.org/projects/func/. It's a Wiki.
+
+See also the manpages for "func", "certmaster", and "certmaster-ca".
+
+=head1 AUTHOR
+
+Various. See https://hosted.fedoraproject.org/projects/func
+
+