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.

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.