Database Schema Updates

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 is generated by the installer. If you deploy web files by other means (for example a development sync script), 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.

Only a full administrator can apply a schema update — specifically, an account holding a role with Administrator (full access) ticked. A role that grants a great deal but not everything is still not enough: a schema update rewrites the whole database, so nothing narrower qualifies. See Roles & Permissions.

Directory-sourced administrators work normally. An LDAP account that lands on a full-access role is an administrator here too.

!!! note “Upgrading from a version before roles existed”

Roles arrived in FOG 1.6, and the schema update itself is what creates
them. On a server still running an older schema there are no roles to
check yet, so FOG falls back to the old account type — meaning your
existing administrator can log in and apply the update exactly as
before. Once that update finishes, roles are in place and the fallback
is gone for good.

The upgrade gives every existing administrator account a role granting
full access, so nobody loses the ability to run future updates.

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.

Recent installers probe the web interface before handing you a URL, so a server in this state will fail the install with a named error rather than reporting success. If your installer said Setup complete and the site is dead, you are on an older installer and should re-run the current one.

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 a full administrator. Open the account under Users → Roles and confirm it holds a role with Administrator (full access) ticked.

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.