# Braintacle documentation

## Project website

Braintacle is hosted at http://savannah.nongnu.org/projects/braintacle.

## What is it?

Braintacle is a set of applications for automatic inventory of hard- and software, software deployment and more. It consists of several parts:

- A patched version of OCS Inventory NG with several improvements, most notably the support for different database backends (PostgreSQL is recommended, but MySQL is still supported). It is contained in the ocsinventory directory. See the README.html file in the same directory for details.
- An alternative administration console which is aimed to replace the original administration console (ocsreports) completely. It is not feature complete yet, but already fully usable for most everyday tasks.
- Some command line helper applications.

## Advantages

- Better integration into your IT infrastructure. Use the DBMS of your choice – no need to maintain an extra MySQL installation if you already have a different DBMS set up. The installation is less intrusive to your server. No more code is copied to obscure locations. All code is run directly from 1 application directory, making maintenance much easier.
- The package builder is much easier to use and provides features that the original console does not have. Most notably, deploying a new version of an existing package is very easy: just click on its name, upload the file, give it a new name and that's it. See "Package builder" for a full list of features.
- Duplicates are much better to manage. You can specify which type of information to merge, and you can blacklist asset tags too, not only serials and MAC addresses.
- Multiple packages can be deployed to a single computer in one step.
- Software listings can be freed of clutter like these boring Windows updates and annoying Office 2007 subpackages. See "software filter" for details.
- Software dictionaries are much easier to manage. Extra categories are not supported yet – The dictionary manager is intended for software filters only.
- In addition to the automatically collected Windows license key, a key can be entered manually. This can be useful if the reported key is garbage (this can happen in certain situations) or if licenses have been reassigned within an organization.
- Consistent navigation – no popups, no more lost menus.
- Computers can be exported as XML, either individually via console or all at once via the export tool. The XML files are similar to those generated locally by the agents, and suitable for import via the console or the ocsinventory-injector.pl script. This simplifies data migration between different databases or data processing via external tools.
- Braintacle uses localization functions wherever possible. Translation is provided by the well-known gettext standard. English and german translations are included. Other translations can easily be added and maintained using your favorite gettext tools.
- As a side-effect of the Zend Framework's MVC architecture, the model classes provide an abstract API to all logical objects (computers, packages etc.) which can be used by third party code.

## Extra features and limitations

### Login restrictions

Braintacle does not implement different access privileges. To prevent unprivileged users from unauthorized access, only administrators can log in.

Braintacle requires an account with an MD5 hashed password. This is the default when creating an account or changing the password. If the database is populated with the bundled OCSInventory console or schema-manager.php, the default account will already have a hashed password. A cleartext 'admin' passord will be converted.

### Package builder

#### Editing packages

Braintacle's most notable feature is the ability to edit existing packages. More precisely, by clicking on the name of a package you invoke the package builder with the old package's metadata already filled in. The package content itself does not get copied to the new package, so you have to upload a file again. This limitation is OK for the typical scenario where you deploy a new software version, so you would have to upload a new file anyway.

After the new package has been successfully built, it will optionally be deployed to computers which already had the old package marked for deployment. Then the old package is deleted. For this reason, the new package needs a different name (typically a different version number appended) because for a brief period of time, both packages exist and package names have to be unique. If anything goes wrong with building the new package, the old package will not be touched.

#### Additional metadata

You can specify a comment and a certificate path. Both fields are already present in the database and the certificate path is really evaluated, but the original GUI always submits hardcoded defaults (empty comment and 'INSTALL_PATH/cacert.pem'). INSTALL_PATH will be expanded to the agent's installation directory (like '%PROGRAMFILES%\Ocs Inventory Agent'). You can set any path and filename you like. The Windows agent also accepts UNC paths (which will probably only work if all clients reside on a local network and the share allows guest access). This allows some cool stuff like changing the HTTPS server's certificate without breaking deployment.

#### On-the-fly ZIP compression

If you want to deploy a single file, having to wrap it into a ZIP archive before uploading can be annoying. Braintacle creates the archive on the fly if the uploaded file is not a ZIP archive (currently only implemented for Windows packages). Since the PHP Zip extension's capabilities are limited and ressource usage can grow high for huge files, you can bypass this feature by creating the archive manually before upload, like you always did.

#### Computation of fragment size

The original GUI allows specifying both the number of fragments and the fragment size. Changing one value automatically affects the other. Braintacle simplifies this process a bit, assuming that you don't want to have a package to have a particular number of fragments, but any number of fragments up to a certain size. You only specify the maximum fragment size (a default can be provided). The actual size may be lower because Braintacle splits the package into evenly-sized fragments up to the given limit.

Since the maximum fragment size is not stored anywhere (except for the default which may not apply to existing packages), it has to be estimated upon editing. The result will almost certainly be different from the original value, but still about the same magnitude. In particular, it would deliver the same number of fragments if the size of the new file had not changed.

#### Upload size limit

Braintacle will try to prevent you from uploading a file that is too big to handle. This is more user-friendly than seeing the script abort prematurely and having to look at the logfiles to find out which one of PHP's limits had been exceeded.

The maximum allowed file size is displayed within the package builder. If this value is too low, adjust the PHP settings. It is the smallest value of these PHP settings:

- 100% of upload_max_filesize
- 90% of post_max_size
- 80% of memory_limit

#### Only 1 download server supported

Braintacle supports only 1 download server. This simplifies not only the code, but also the workflow. The code is written with the assumption that there is only 1 download server per package. Having more than 1 download server can give unpredictable results. Use at your own risk!

If ressource usage is a problem on your server, you should consider solving the problem outside the application. For example, you could force usage of a caching proxy on external sites or set up a load balancer. Once set up this may be easier to handle than having to deal with this everytime you build a new package.

#### Automatic activation

The limitation to 1 download server allows package creation and activation to be merged into a single step. The download locations must be specified at build time, where defaults can be provided.

#### Secure hashes

Since MD5 hashes are insecure, SHA1 hashes are used instead. This is already supported by the agent, but the OCS GUI does not make use of this feature.

#### More reliable connection testing

The HTTP and HTTPS connections are checked without using fopen() wrappers. These checks now work even if allow_url_fopen is disabled.

Note that success or failure of these tests does not necessarily mean that the download will or will not work. Different proxy configuration, firewalls and name resolution may give a different result on the client. The test results only indicate success or failure on the server that runs Braintacle. It's up to you to interpret the results.

### Software filter

OCS Inventory provides a function called "software dictionaries" where pieces of installed software can be tagged to be ignored. This is intended for interaction with GLPI. The OCS Inventory console only provides an interface to define these lists, but does not make use of it.

Braintacle honours this list and does not display any software which is tagged to be ignored. If you already use GLPI and make use of this feature, this behavior might not be desired. There is an option to display all software anyway.

Some software (like MS Office 2007) causes multiple identical entries in a computer's inventory. These duplicate entries are hidden by default, but can be shown with a single mouseclick if you are really interested.

### Network management (aka IP discovery)

Braintacle uses a different method to determine which network a computer belongs to. In particular, it takes the netmask into account (for example, 192.168.0.0/16 is different from 192.168.0.0/24) and also ignores 127.0.0.0/8 completely as this is not a real network. Additionally, interfaces belonging to an inventoried computer will never show up as unknown, even if the inventory is out of date.

### Installing packages on a computer

Multiple packages can be deployed to a computer at once instead of picking them one by one. This is particularly convenient for fresh installs where a lot of packages have to be installed.

The list of installable packages does not contain already installed packages, which would only end up with ERR_ALREADY_SETUP. If a package is not in the list, it would not be installable anyway. This also keeps the list as short as possible.

### Managing duplicates

Braintacle supports a blacklist for asset tags, in addition to serials and MAC addresses.

The implementation for merging duplicates is more robust – no more database errors on weird combinations.

The information to be merged can be specified in detail:

- User defined information, if selected, will be preserved from the oldest entry.
- Manual group assignments, if selected, will be combined from all older entries.
- Package assignments, if selected, will be combined from all older entries. The package history is intentionally not preserved. The typical origin of duplicates is a reinstall, where this would just get in the way.

## Known issues

### Apache gives 404 error on certain operations

These strange 404 errors come directly from Apache. They don't even show up in the error log.

The source of this problem is the AllowEncodedSlashes directive. If this is disabled (the default), URLs which contain encoded slashes (%2F) trigger this 404.

I have not found any information about the purpose of this behavior and the consequences of changing it. I suppose this is a lame attempt to stop path traversal attacks on poorly written scripts.

There are several ways to work around this problem at application level, but they are all very messy. For this reason, I have not implemented any and the only way to solve this problem is to set `AllowEncodedSlashes On` for the virtual host.

## Managing the database

There are 2 use cases that require different methods for database management.

### Using Braintacle in addition to an original OCS Inventory NG installation

Use the OCS Inventory installer to manage the database. Do not use Braintacle's schema manager.

### Using Braintacle with its bundled communication server

Braintacle manages the database with the script tools/schema-manager.php. Please note that Braintacle's schema is slightly different from the original schema. See the schema documentation for details.

This schema is not fully compatible with the original version of OCS Inventory NG. It can only be used with the communication server that comes bundled with Braintacle. Do not use schema-manager.php if you use a non-Braintacle server. Manage the schema through the original console application in that case.

The schema manager checks for compatibility with the original version and refuses to update the database in that case. This can be overridden with the --force option, but compatibility will be lost.

Braintacle and its bundled communication server work with both schema types, but some features will only be available with the Braintacle schema.

#### Creating the database

This is documented in the installation instructions for the communication server. See ocsinventory/README.html for details.

#### Updating the database

When the schema has changed, just run the schema manager again. It will update the tables to the new schema. It's strongly recommend to back up the database before you do this. Updating a database with MDB2_Schema is a complex operation. Despite intensive testing and bugfixing, there could always something go wrong.

It is safe to run the schema manager more than once, even if the schema has not changed. It's strongly recommended to run it after every application upgrade. The script will detect if a schema upgrade is required and perform it, or abort if not.

## Helper applications

The tools directory contains some scripts that are not part of the application, but intended to be invoked directly via command line when needed.

### schema-manager.php

This script is described above.

### export.php

This script exports all computers in the database to the directory specified via the --dir or -d argument. It will generate 1 XML file per computer. The generated files can optionally be validated via the --validate or -v switch.

### createpackage.php

This script creates a package from the command line. This is useful if a file is too big to be uploaded to the webserver. It can also be used as part of a package builder script.

It is limited to the package builder defaults. Only the name and the file itself can be specified.

Don't forget to change permissions/ownership of the generated directory and files. Otherwise the webserver won't be able to read and/or delete them. You could also use `su` to run this script with the UID of the webserver:

    su -c 'php tools/createpackage-php PackageName install-Package.exe' www-data

The script is also an example for using the Braintacle API in a different application.

### update-translation.php

This script can be used to maintain the translation files. It requires xgettext, msgmerge and msgfmt in your search path. It does 3 things:

1. It extracts all translatable strings from the PHP source files and updates languages/braintacle.pot. This operation can be skipped by passing the `--noextract` option.
   By default, the update is done only if changes to the strings are detected. If only line numbers have changed, nothing is done in this stage. An update can be forced with the `--force` option.
2. It updates all .po files in languages/<language>/.
3. It compiles the .po files to .mo files in languages/<language>/LC_MESSAGES/ which are used by the application.

Run this script everytime you have added translatable stings to the source code or when you have updated the translation.

### generate-documentation.php

This script generates/updates the API documentation. It requires phpDocumentor 2 to be installed. It will not work with older phpDocumentor versions.

If no argument is given, phpDocumentor is invoked via the 'phpdoc' command. If this is not available or a different version (a development snapshot, for example) should be used, specify the path to the phpDocumentor installation:

`php tools/generate-documentation.php /path/to/phpDocumentor2`