From 697402da24ca930b3608359a61b9872fdddc62d9 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Thu, 7 Feb 2008 12:08:55 -0500 Subject: 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 --- docs/.gitignore | 2 + docs/Makefile | 7 +++ docs/certmaster-ca.pod | 41 ++++++++++++++++++ docs/certmaster.pod | 29 +++++++++++++ docs/func-inventory.pod | 70 ++++++++++++++++++++++++++++++ docs/func.pod | 111 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/funcd.pod | 25 +++++++++++ 7 files changed, 285 insertions(+) create mode 100644 docs/.gitignore create mode 100755 docs/Makefile create mode 100644 docs/certmaster-ca.pod create mode 100644 docs/certmaster.pod create mode 100644 docs/func-inventory.pod create mode 100644 docs/func.pod create mode 100644 docs/funcd.pod (limited to 'docs') 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 + + + 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 [ 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 + + -- cgit