Use the admin

This page is for the person who runs the server. It covers how to create admin logins, how sign-in and two-step codes work, which actions ask for your password again, and a tour of the admin screens. When you finish, you can sign in safely and find everything you need to run your frames day to day.

The admin is a desktop web page at https://frames.example.com/frames/admin/. It is built for a computer, not a phone.

Manage admin users

Admin logins live in the database. You create them from the command line on the server, as the web user. Nobody can sign in until a user exists.

sudo -u www-data php /srv/frame/app/bin/user.php <command> [user name]

passwd, totp-enable and totp-disable also sign that user out of every browser at once and make that user's trusted-device cookie stop working.

Rules:

• The command refuses to run as root. Run it as the web user, as shown, so the database keeps the right owner.
• User names are lowercase letters, digits, dot, underscore and hyphen, up to 64 characters, and start with a letter or digit.
• The sign-in form ignores capital letters and spaces around the name.
• A password must be at least 12 characters. It cannot match the user name, and it cannot be on the bundled list of commonly used passwords. The limit is 1024 bytes, or 72 bytes if your PHP has no Argon2 support and the server uses bcrypt.
• The password is read from the terminal with echo off. To pass it without a terminal, pipe one line into the command. Never put a password on the command line.
• If the database is missing or out of date, the command stops and tells you to run migrate.php first.

Passwords are stored as Argon2id hashes.

Two-step sign-in

A password alone is the only thing between the internet and your frames. Add a one-time code from an authenticator app. It is strongly recommended.

1. Run:

   sudo -u www-data php /srv/frame/app/bin/user.php totp-enable yourname
   

2. The command prints a secret: and an otpauth:// link. In your authenticator app, choose to add an account by entering a setup key, and type the secret. The link holds the same secret.

3. At the prompt, enter the six-digit code your app shows.

Nothing is saved until the code checks out. If two-step sign-in is already on for that user, run totp-disable first.

After that, the sign-in form needs the password and the current code together. A wrong password and a wrong code give the same message, so nobody can tell which was wrong.

Details:

• The codes are standard time-based codes: six digits, a new one every 30 seconds, SHA-1. The app name shown is "Frames admin".
• The server accepts the current code and the ones just before and after it, to allow for clock drift. Your server's clock must be right, so run NTP on it.
• A code works once. Entering the same code a second time fails.

If you lose the authenticator, you recover from the shell, which only you have:

sudo -u www-data php /srv/frame/app/bin/user.php totp-disable yourname

Sign in and out

1. Open https://frames.example.com/frames/admin/. You land on the sign-in page.
2. Enter your User name and Password.
3. If two-step sign-in is on, enter the Authentication code. Leave it empty otherwise.
4. Select Sign in.

You land on Frames.

To sign out, open the account menu in the top-right corner (it shows your user name) and select Sign out.

Messages you might see on the sign-in page:

Sessions and timeouts

When a session ends, the admin shows a Signed out box with a Sign in button. Unsaved edits on that page are lost.

A password change, a two-step change, or removing the user ends that user's sessions at once.

Trusted device

When you sign in successfully, your browser keeps a trusted-device cookie for 90 days. It does exactly one thing: it lifts the per-user lockout described below for that browser. It never skips the password or the code.

The cookie stops working when that user's password changes, two-step sign-in is turned on or off, or the user is removed. The key that signs these cookies is var/device.key, created the first time someone signs in. Deleting it invalidates every trusted-device cookie and changes nothing else.

Confirming a risky action

Some actions ask for your password (and your code, if two-step is on) again, unless you entered it in the last five minutes. Signing in counts. When it asks, the Confirm it's you box appears with Password and Authentication code fields and a Confirm button. After you confirm, the action goes ahead.

If you select Cancel, the admin says "Not confirmed. Nothing was changed."

These actions ask:

Lockouts

The sign-in page counts failed attempts. Every attempt counts, including ones with a wrong code.

While a lockout is active, a correct password is refused too. Wait it out. The sign-in page says "Too many attempts. Try again later."

Re-confirming your password inside the admin uses the per-address limit only, so someone guessing at your user name cannot stop you from confirming an action.

If a proxy hides client addresses, everyone shares one address and a few failures lock the page for all. Set client_ip_header and trusted_proxies. See Install the frame server.

What the server logs

Sign-ins and failures go to the PHP error log, one line each, without passwords:

frame admin: login ok user=yourname ip=203.0.113.9
frame admin: login failed user=yourname ip=203.0.113.9
frame admin: login throttled ip=203.0.113.9
frame admin: login rejected origin ip=203.0.113.9
frame admin: login rejected token ip=203.0.113.9
frame admin: logout user=yourname
frame admin: reauth failed user=yourname ip=203.0.113.9
frame admin: reauth throttled ip=203.0.113.9

Kiosk release changes, such as uploads and roll-outs, are logged the same way. See Update the kiosk.

You can point fail2ban at the login failed, login throttled, login rejected and reauth failed lines.

A tour of the admin

The top bar has the Frames admin name, four links, and your account menu.

Every page uses a hash address, such as #/photos or #/frame/<id>/widgets, so you can bookmark any screen.

Frames

Frames shows one tile per claimed frame. Each tile has the last screenshot, the frame's name, and a status: Online, Offline (with when it was last seen), Never connected, or Revoked. A Weak Wi-Fi badge shows when the signal is below -75 dBm. An Update available badge shows when another frame runs a newer kiosk. The page refreshes every minute.

Claim a frame

A new frame shows a six-digit pairing code on its screen. A banner on Frames says "A frame is waiting to be claimed." with Claim it and Dismiss buttons.

1. Select Claim a frame.
2. Enter the six-digit code from the frame's screen in Code. The box finds the frame as soon as you type six digits. You can also select Find frame.
3. Check the frame ID the admin shows. Confirm it is the one in front of you.
4. Enter a Name for the frame. It is shown in the admin and nowhere else.
5. Select Claim frame.

You see "Claimed. Turn on the widgets you want." The admin opens the frame's Widgets section.

The code is valid for 24 hours. After five wrong codes in 10 minutes, the admin stops accepting codes for a while. The message is "That code was wrong or has expired."

When you claim a frame, the server also:

• turns on the Clock and Calendar widgets, and Weather if a location already exists,
• picks a time for the daily photo set, between 04:00 and 06:00 in the frame's time zone, and
• points the frame at the newest kiosk release that has already run on a frame, if there is one. See Update the kiosk.

Dismiss deletes unclaimed frames. It asks you to confirm your password. Any that are still powered on enroll again.

The frame page

Select a tile to open a frame. The header shows the frame's name (use the pencil button to rename it) and its status. The More menu has Revoke (or Restore) and Delete.

• Revoke stops a frame working at once. You can restore it later.
• Restore brings a revoked frame back.
• Delete removes the frame and its settings. If the frame is still powered on, it enrolls again as unclaimed. The dialog offers Revoke instead.

All three ask for your password again.

A rail on the left lists the frame's sections: Screen, Schedule, Widgets, one section per widget that has settings (shown while the widget is on), Security and Details. A dot next to a section means unsaved changes there.

Each section saves on its own. A bar at the bottom shows "Unsaved changes" with Discard and Save. If you try to leave with unsaved changes, the admin asks "Discard unsaved changes?"

Live view

Screen shows what the frame is showing. Select Refresh to ask the frame for a new screenshot.

• The frame picks up the request on its next check-in. This usually takes a few seconds, and the admin waits up to 45 seconds. After 25 seconds it says "Taking longer than usual."
• You can ask again 10 seconds after the last request.
• If the screen was off, the picture is a "Screen off" placeholder and the caption says when it turned off and when it comes back.
• If the frame is offline, the admin says "Offline, so no live view." and offers Check again.
• Frames running an older kiosk say "This frame's software is too old for live view."

Only the latest screenshot of each frame is kept, as a JPEG of up to 600 KiB.

Schedule and bedtime

Schedule controls when the screen turns fully off how long the frame waits before it starts the screensaver, and which time zone the frame uses.

1. Turn on Turn the screen off overnight.
2. Set Bedtime and Wake time. Type a time into each, or drag the moon and sun handles on the 24-hour bar. With the keyboard, the arrow keys move a handle by 5 minutes and Page Up and Page Down move it by an hour.
3. Select Save.

Time zone. New frames start with America/New_York. Bedtime, wake time, the daily photo pick time and the clock all use the frame's time zone. To change it, type in Time zone to search the list, for example America/Chicago, or select Use this computer's zone. Select Save. The frame picks it up on its next check-in, within a minute.

Rules:

• Bedtime and wake time must differ. The 24-hour bar keeps its two handles at least 15 minutes apart. Dragging snaps to 15 minutes, or 5 minutes while you hold Shift.
• When the switch is off, the bar says "Screen stays on all day."
• A line under the bar says how long the screen is off and on, and whether it is on or off right now.
• The schedule is saved on the frame, so it works when the frame is offline.
• At bedtime the backlight goes fully off, not just dim. A tap wakes it.

Screensaver

On the same page, Start screensaver after sets how long the frame waits without a touch before it starts the photo screensaver. The choices are 30 seconds, 1, 2, 5, 10, 15 and 30 minutes, and 1 hour. The default is 2 minutes. If the frame has no photos, it returns to the home screen instead. The photos come from the frame's daily set. See Photos.

Widgets

Widgets has an On and Off switch for each widget. Turn switches on or off and select Save. Settings for each widget appear in their own section once it is on. See Widgets.

Security

Security sets the frame's PIN, the one the frame asks for after you hold the top-left corner for 10 seconds. The panel says whether the frame uses a custom PIN or the factory PIN, which is the KIOSK_PIN baked into the build.

1. Enter the New PIN, 4 to 8 digits. Use the eye button to see what you typed.
2. Select Set PIN. It asks for your password.

Reset to factory PIN clears the custom PIN. The frame picks up the change on its next check-in.

Details

Details is a read-only summary: the Wi-Fi network and signal, the local and public IP, the MAC address, when it last checked in, the versions it runs, its uptime, its short ID, its time zone and when it enrolled. The Kiosk version row is where you send it a new kiosk. See Update the kiosk.

Library

Library holds three lists.

Locations. Weather needs at least one. Select Add location, then fill in:

Leave Stations empty at first. The pencil edits a location and Delete removes it. The admin refuses to delete a location a frame's Weather widget uses.

Calendars. Select Add calendar and enter:

The table shows each calendar's host and a status: OK, Error (with the message), or Not fetched. Rename and Delete are on each row. The admin refuses to delete a calendar a frame uses.

Kiosk app. The list of kiosk releases, with Upload release. See Update the kiosk.

Photos and Card designs

These pages are covered where the feature is explained:

• Photos: Photos.
• Card designs: Widgets: Cards.

Related

• Install the frame server
• Widgets
• Photos
• Update the kiosk
• Security

Next: Build the kiosk and set up a frame.