diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/conf.py | 2 | ||||
-rw-r--r-- | doc/exts/xmlschema.py | 7 | ||||
-rw-r--r-- | doc/help/troubleshooting.txt | 4 | ||||
-rw-r--r-- | doc/installation/prerequisites.txt | 14 | ||||
-rw-r--r-- | doc/man/bcfg2.conf.txt | 12 | ||||
-rw-r--r-- | doc/man/bcfg2.txt | 9 | ||||
-rw-r--r-- | doc/reports/dynamic.txt | 36 | ||||
-rw-r--r-- | doc/server/plugins/generators/packages.txt | 16 | ||||
-rw-r--r-- | doc/server/plugins/grouping/metadata.txt | 69 | ||||
-rw-r--r-- | doc/server/plugins/version/git.txt | 6 |
10 files changed, 69 insertions, 106 deletions
diff --git a/doc/conf.py b/doc/conf.py index a1bceb1b1..d3d30687b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -66,7 +66,7 @@ else: # The short X.Y version. version = '1.3' # The full version, including alpha/beta/rc tags. -release = '1.3.0' +release = '1.3.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/exts/xmlschema.py b/doc/exts/xmlschema.py index 727b4bbd0..24cbf2e2d 100644 --- a/doc/exts/xmlschema.py +++ b/doc/exts/xmlschema.py @@ -76,6 +76,11 @@ from sphinx.util.nodes import make_refnode, split_explicit_title, \ from sphinx.util.compat import Directive from sphinx.domains import ObjType, Domain +try: + from new import classobj +except ImportError: + classobj = type + XS = "http://www.w3.org/2001/XMLSchema" XS_NS = "{%s}" % XS NSMAP = dict(xs=XS) @@ -653,7 +658,7 @@ def append_node(parent, cls_or_node, *contents): def build_node(cls_or_node, *contents): - if isinstance(cls_or_node, type): + if isinstance(cls_or_node, (type, classobj)): rv = cls_or_node() else: rv = cls_or_node diff --git a/doc/help/troubleshooting.txt b/doc/help/troubleshooting.txt index c3abab9e7..5ae668c89 100644 --- a/doc/help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -56,8 +56,8 @@ the debug level individually on a given plugin, e.g.:: Finally, the File Activity Monitor has its own analogue to these two methods, for setting the debug level of the FAM: - bcfg2-admin xcmd toggle_fam_debug - bcfg2-admin xcmd set_fam_debug false + bcfg2-admin xcmd Inotify.toggle_debug + bcfg2-admin xcmd Inotify.set_debug false Check if all repository XML files conform to schemas ==================================================== diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt index eaa2a0393..81ac12632 100644 --- a/doc/installation/prerequisites.txt +++ b/doc/installation/prerequisites.txt @@ -59,3 +59,17 @@ Bcfg2 Server | included in python versions | | | | 2.6 and later | | | +-------------------------------+----------+--------------------------------+ + +Bcfg2 Reporting +--------------- + +A webserver capabable of running wsgi applications is required for web reporting, +such as Apache + mod_wsgi or nginx. + ++-------------------------------+----------+--------------------------------+ +| Software | Version | Requires | ++===============================+==========+================================+ +| django | 1.2.0+ | | ++-------------------------------+----------+--------------------------------+ +| south | 0.7.0+ | | ++-------------------------------+----------+--------------------------------+ diff --git a/doc/man/bcfg2.conf.txt b/doc/man/bcfg2.conf.txt index ffc202f7f..f5516cbbd 100644 --- a/doc/man/bcfg2.conf.txt +++ b/doc/man/bcfg2.conf.txt @@ -719,11 +719,21 @@ control the database connection of the server. port Port for database connections. Not used for sqlite3. +Reporting options +----------------- + + config + Specifies the location of the reporting configuration (default + is /etc/bcfg2-web.conf. + time_zone - Specify a time zone other than that used on the system. (Note + Specifies a time zone other than that used on the system. (Note that this will cause the Bcfg2 server to log messages in this time zone as well). + web_debug + Turn on Django debugging. + See Also -------- diff --git a/doc/man/bcfg2.txt b/doc/man/bcfg2.txt index 6a77a4a3c..6df4f9b4f 100644 --- a/doc/man/bcfg2.txt +++ b/doc/man/bcfg2.txt @@ -88,10 +88,13 @@ Options the constraints of correctness, and thus should only be used in safe conditions. -r mode Cause bcfg2 to remove extra configuration elements - it detects. Mode is one of "all", "Services", or - "Packages". "all" removes all entries. Likewise, - "Services" and "Packages" remove only the extra + it detects. Mode is one of "all", "Services", + "Packages", or "Users". "all" removes all extra entries. + "Services", "Packages", and "Users" remove only the extra configuration elements of the respective type. + ("Services" actually just disables extra services, + since they can't be removed, and "Users" removes + extra POSIXUser and POSIXUser entries.) -s servicemode Set bcfg2 interaction level for services. Default behavior is to modify all services affected by reconfiguration. "build" mode attempts to stop all diff --git a/doc/reports/dynamic.txt b/doc/reports/dynamic.txt index 19c947a71..b3028e9e1 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -56,7 +56,7 @@ Install Be sure to include the specified fields included in the example ``bcfg2.conf`` file. These can be specified in either ``/etc/bcfg2.conf``, if it is readable by the webserver user, or ``/etc/bcfg2-web.conf``. Any -database supported by `Django <http://www.djangoproject.com>`_ can be used. +database supported by `Django <http://www.djangoproject.com>`_ can be used. As of version 1.3, `South <http://south.aeracode.org>`_ is used to control schema changes. If your database is not supported by South, any updates will need to be applied manually. Sqlite is configured by default. @@ -78,11 +78,11 @@ databases. After configuring your database be sure to run `bcfg2-admin reports init` to create the schema. -To enable statistics collection in the bcfg2-server, add +To enable statistics collection in the bcfg2-server, add :ref:`server-plugins-statistics-reporting` to the **plugins** line in your ``bcfg2.conf`` and restart the bcfg2-server. A report collecting -daemon should be run to import the collected statistics into the backend. -Please see the section :ref:`Report Collector <report_collector>` for more +daemon should be run to import the collected statistics into the backend. +Please see the section :ref:`Report Collector <report_collector>` for more information. Detailed installation instructions can be found :ref:`here @@ -155,7 +155,7 @@ http://localhost/bcfg2 and see the new reports. Upgrading ============ -1. Convert database config +1. Convert database config Run `tools/upgrade/1.3/migrate_configs.py` @@ -166,32 +166,34 @@ Upgrading 2. Replace the DBStats plugin with the Reporting plugin. 3. Migrate historic data. - Run `tools/upgrade/1.3/migrate_dbstats.py` + Run ``tools/upgrade/1.3/migrate_dbstats.py`` The reporting schema is now managed using `South <http://south.aeracode.org>`_ instead of a set of custom scripts. This creates the new schema and imports all of the historic data to the new format. -.. Note: + .. note:: - After the database is upgraded all of the old tables are left intact. To - remove them any table starting with reports_ can be dropped. + After the database is upgraded all of the old tables are left + intact. To remove them any table starting with reports_ can + be dropped. 4. `(Optional)` Run the :ref:`Report Collector <report_collector>` - Add "transport = LocalFilesystem" under "[reporting]" in `bcfg2.conf`. - Restart the bcfg2-server and start the bcfg2-report-collector. + Add "transport = LocalFilesystem" under "[reporting]" in + ``bcfg2.conf``. Restart the bcfg2-server and start the + bcfg2-report-collector. Configuring =========== -Most of the configuration is handled through the ``/etc/bcfg2.conf`` or alternatively -``/etc/bcfg2-web.conf``. +Most of the configuration is handled through the ``/etc/bcfg2.conf`` +or alternatively ``/etc/bcfg2-web.conf``. An example using the defaults is listed below:: [database] engine = sqlite3 - name = '/var/lib/bcfg2/etc/bcfg2.sqlite' + name = /var/lib/bcfg2/etc/bcfg2.sqlite user = password = host = @@ -260,7 +262,7 @@ reporting Statistics Transports --------------------- -A transport is required to pass the data collected from the bcfg2-server +A transport is required to pass the data collected from the bcfg2-server to the bcfg2-report-collector. At the time of this writing two transports are available: @@ -271,7 +273,7 @@ are available: Future transports will allow multiple servers to pass data to a single or multiple bcfg2-report-collector processes. New installations default to and should use the -LocalFilesystem transport. Upgrades will use DirectStore by default in the 1.3 +LocalFilesystem transport. Upgrades will use DirectStore by default in the 1.3 release. .. Note:: @@ -293,7 +295,7 @@ An example configuration with the default values:: redis_port = 6379 redis_db = 0 -bcfg2-admin commands operate slightly differently in this mode. Instead of querying the +bcfg2-admin commands operate slightly differently in this mode. Instead of querying the database directly, rpc commands are issued to the report collectors. This only affects the minestruct and pull commands. diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index b11d1ebc5..95bf4238a 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -217,7 +217,8 @@ something like this: <Source type="apt" recommended="true" ...> .. warning:: You must regenerate the Packages cache when adding or - removing the recommended attribute. + removing the recommended attribute (``bcfg2-admin xcmd + Packages.Refresh``). .. [#f1] Bcfg2 will by default add **Essential** packages to the client specification. You can disable this behavior by @@ -321,9 +322,9 @@ will report information like:: Packages: Updating http://mirror.centos.org/centos/5/extras/x86_64/repodata/filelists.xml.gz Packages: Updating http://mirror.centos.org/centos/5/extras/x86_64/repodata/primary.xml.gz -Once line per file download needed. ``Packages/sources.xml`` will -be reloaded at this time, so any source specification changes (new -or modified sources in this file) will be reflected by the server at +One line per file download needed. ``Packages/sources.xml`` will be +reloaded at this time, so any source specification changes (new or +modified sources in this file) will be reflected by the server at this point. This process is much, much faster if you use the :ref:`native yum @@ -426,7 +427,6 @@ Benefits to this include: * Much lower memory usage by the ``bcfg2-server`` process. * Much faster ``Packages.Refresh`` behavior. * More accurate dependency resolution. -* Support for package groups. Drawbacks include: @@ -475,9 +475,9 @@ generally be overridden: Package Groups -------------- -Yum package groups are supported by the native Yum libraries. To -include a package group, use the -:xml:attribute:`PackageStructure:group` attribute of the +Yum package groups are supported by both the native Yum libraries and +Bcfg2's internal dependency resolver. To include a package group, use +the :xml:attribute:`PackageStructure:group` attribute of the :xml:element:`Package` tag. You can use either the short group ID or the long group name: diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index f690aac8b..9fe87c878 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -204,74 +204,9 @@ A special client metadata class is available to :ref:`server-plugins-generators-cfg-genshi` and :ref:`server-plugins-generators-cfg-cheetah`. -+------------+------------------------------------------------+---------------+ -| Attribute | Description | Value | -+============+================================================+===============+ -| hostname | Client hostname | String | -+------------+------------------------------------------------+---------------+ -| profile | Client profile | String | -+------------+------------------------------------------------+---------------+ -| aliases | Client aliases | List | -+------------+------------------------------------------------+---------------+ -| addresses | Adresses this client is known by | List | -+------------+------------------------------------------------+---------------+ -| groups | Groups this client is a member of | List | -+------------+------------------------------------------------+---------------+ -| categories | Categories of this clients groups | List | -+------------+------------------------------------------------+---------------+ -| uuid | uuid identifier for this client | String | -+------------+------------------------------------------------+---------------+ -| password | bcfg password for this client | String | -+------------+------------------------------------------------+---------------+ -| connectors | connector plugins known to this client | List | -+------------+------------------------------------------------+---------------+ -| query | `MetadataQuery`_ object | MetadataQuery | -+------------+------------------------------------------------+---------------+ - - -+-----------------------------+------------------------------------------------+-------------------+ -| Method | Description | Value | -+=============================+================================================+===================+ -| inGroup(group) | True if this client is a memnber of 'group' | Boolean | -+-----------------------------+------------------------------------------------+-------------------+ -| group_in_category(category) | Returns the group in 'category' if the client | String | -| | is a member of 'category', otherwise '' | | -+-----------------------------+------------------------------------------------+-------------------+ +.. autoclass:: Bcfg2.Server.Plugins.Metadata.ClientMetadata MetadataQuery ------------- -This class provides query methods for the metadata of all clients -known to the Bcfg2 server. Note that ``*by_groups()`` and -``*by_profiles()`` behave differently; for a client to be included in -the return value of a ``by_groups()`` method, it must be a member of -*all* groups listed in the argument; for a client to be included in -the return value of a ``by_profiles()`` method, it must have any group -listed as its profile group. - -+------------------------------+------------------------------------------------+-------------------+ -| Method | Description | Value | -+==============================+================================================+===================+ -| by_name(client) | Get ClientMetadata object for 'client' | ClientMetadata | -+------------------------------+------------------------------------------------+-------------------+ -| by_groups(groups) | Get ClientMetadata object for clients in all | List of | -| | listed groups | ClientMetadata | -+------------------------------+------------------------------------------------+-------------------+ -| by_profiles(client) | Get ClientMetadata objects for clients whose | List of | -| | profile matches any listed profile group | ClientMetadata | -+------------------------------+------------------------------------------------+-------------------+ -| names_by_groups(groups) | Get the names of all clients in all listed | List of strings | -| | groups | | -+------------------------------+------------------------------------------------+-------------------+ -| names_by_profiles(profiles) | Get the names of clients whose profile matches | List of strings | -| | any listed profile group | | -+------------------------------+------------------------------------------------+-------------------+ -| all_clients() | All known client hostnames | List of strings | -+------------------------------+------------------------------------------------+-------------------+ -| all_groups() | All known group names | List of strings | -+------------------------------+------------------------------------------------+-------------------+ -| all_groups_in_category(cat) | The names of all groups in category 'cat' | List of strings | -+------------------------------+------------------------------------------------+-------------------+ -| all() | Get ClientMetadata for all clients | List of | -| | | ClientMetadata | -+------------------------------+------------------------------------------------+-------------------+ +.. autoclass:: Bcfg2.Server.Plugins.Metadata.MetadataQuery diff --git a/doc/server/plugins/version/git.txt b/doc/server/plugins/version/git.txt index 3f7ab9d9b..64ff422ca 100644 --- a/doc/server/plugins/version/git.txt +++ b/doc/server/plugins/version/git.txt @@ -13,12 +13,6 @@ reporting purposes. Once the plugin is enabled, every time a client checks in, it will include the current repository revision in the reports/statistics. -As with the other Version plugins, the Git plugin enables you to get -revision information out of your repository for reporting -purposes. Once the plugin is enabled, every time a client checks in, -it will include the current repository revision in the -reports/statistics. - Additionally, if the ``GitPython`` library is installed, the Git plugin exposes an additional XML-RPC method call, ``Git.Update``. With no arguments, ``Git.Update`` updates the working copy to the |