Database Schema Updates (1.5)

This page describes FOG 1.5.

See the 1.6 version of this page for FOG 1.6.

Every FOG release ships with a schema version. When the schema version in your database is lower than the version the web code expects, FOG redirects you to the Database Schema Installer / Updater page and refuses to do anything else until the schema is applied.

The installer normally applies it for you. This page explains who is allowed to run it, what the install token is for, and what to do when the page will not load or will not accept you.

Who is allowed to run it

The schema updater has to work in two very different situations: a brand new server where no FOG user exists yet, and an existing server being upgraded. It accepts three different credentials, and which one applies depends on your situation.

Situation	What authorizes the update
The installer running non-interactively	The install token, sent as a request header
Upgrading an existing server, by hand	Logging in as a FOG administrator
A brand new server, by hand	The install token, in the URL

You do not normally need to think about any of this. Running installfog.sh and answering Y to the schema prompt takes the first path and finishes the job without any URL to visit.

The install token

When the installer deploys the web files it generates a random token and writes it into lib/fog/config.class.php as FOG_SCHEMA_INSTALL_TOKEN. The token exists so that a brand new server — which has no users, and therefore no way to log in — can still apply its first schema without leaving the endpoint open to anyone on the network.

The token is only accepted in a URL while the server still has no FOG users. The moment the first schema deploy completes it creates the default fog user, and from then on the URL form of the token is refused. This is deliberate: that copy of the token is printed to your terminal, saved in the installer’s log, and lands in your browser history, so it should stop being useful as soon as it is no longer needed.

The header form of the token is not restricted this way, because a request header cannot be triggered by a link, a form on another site, or an image tag. That is the form the installer itself uses, on fresh installs and upgrades alike.

Note

config.class.php (at lib/fog/config.class.php on this version — note the path differs from 1.6’s commons/config.class.php) is generated by the installer. If you deploy web files by other means, the file is not regenerated and may have no token in it at all. Re-run the installer if you need the token path to work.

Upgrading an existing server

On an upgrade you do not need a token and will not be shown one. Open:

http(s)://<your-fog-server>/fog/management/index.php?node=schema

Log in as a FOG administrator, then click Install/Update. Logging in anywhere in the web interface will bring you back to this page for as long as the schema is out of date.

This version has no roles system. Authorization is a plain account-type flag on the user: an administrator account (type = 0) is allowed to run the schema update, and anything else is not. There is no partial-access role to worry about here — it is a single yes/no check on the account type, with LDAP accounts mapped onto it the same way, so a directory-sourced administrator works normally too.

Compare with 1.6

1.6 replaces this flag with a full roles system, and the schema update itself is what creates those roles on an upgrade — see the 1.6 version of this page. On this version there is nothing to migrate: the account-type check has always been how authorization works here.

If you cannot log in

If you have lost the administrator password, the browser path is not available to you. Re-run the installer from a shell on the FOG server:

cd /path/to/fogproject/bin
./installfog.sh

Answer Y when it asks whether to install/update the database schema. The installer authorizes itself with the header form of the token and does not need a login.

Troubleshooting

The schema page is blank, or returns HTTP 500

A completely blank white page — no FOG logo, no text, nothing — is almost always a PHP fatal error rather than a database problem. When PHP dies before writing any output, the server returns an empty response with a 500 status, which most browsers render as a blank page.

Check, in this order:

1. Your PHP version. Run php -v on the FOG server. FOG requires PHP 7.4 or newer.
2. The web server’s error log. On Debian/Ubuntu this is usually /var/log/apache2/error.log or /var/log/nginx/error.log; on RHEL-family systems /var/log/httpd/error_log. A line beginning PHP Fatal error: is the answer.
3. The FOG installer log, at error_logs/foginstall.log inside the directory you ran the installer from.

The schema page says “Unauthorized”

You reached the page but the update was refused. Most often this means you used a tokenized URL on a server that already has users — that form is only accepted on a server with no users yet. Log in as an administrator instead, as described above.

It can also mean you are logged in as an account that is not an administrator account (type = 0).

The schema page says the database is not available

The page loaded but cannot reach MySQL. Check the credentials in lib/fog/config.class.php against your database, confirm the database service is running, and confirm the filesystem has free space.

The installer says the schema is still at an old version

The installer verifies the deployed schema against the version the code expects, and stops rather than reporting success if they do not match. This means the update did not actually run. Work through the blank-page checks above — the most common cause is that the web interface was never able to serve the schema page in the first place.