Home / Help / Spherifyer

Help

Spherifyer documentation

How to install and use Spherifyer. At the end you will find an overview of all settings to look things up.

Version 1.x

Overview

Spherifyer shows you at a glance how your VMware environment is doing: how full the datastores are, which VMs use how much, and where there are problems. To do this, it regularly asks your vCenter for its data and keeps the values. That way you also see how usage develops over weeks and months.

Spherifyer runs on one of your own servers. It is a single program file that needs nothing else. Your data stays with you. The program only contacts www.wedigo.net for updates. Spherifyer is free, without a license key and without limits.

You use Spherifyer in two ways:

  • In the browser: the dashboard with all views. This is where you work day to day.
  • In a console window: when started in a console, a simple text interface appears. It shows the state of the program and sets up the service. When Spherifyer runs as a service in the background, you do not need it. Like the text interface, the log file, the messages in the console window and the output of the commands are in English.
The console window: figures and state at a glance
The console window: figures and state at a glance
The VM table of the dashboard
The VM table of the dashboard

Requirements

  • A server running Windows or Linux (64-bit). A VM of its own is perfectly fine.
  • A vCenter user that may only read. Best create a user just for this and give it the Read-only role. Assign the role at the very top of the vCenter and tick *Propagate to children*. Spherifyer never changes anything in vCenter.
  • Network connections:
    • from the Spherifyer server to the vCenter (HTTPS, port 443)
    • from the Spherifyer server to www.wedigo.net (HTTPS, port 443) for updates. A proxy is possible.
    • from your workstation to the dashboard. At first it is only reachable on the server itself, see Access from other computers.

Installation

Download Spherifyer for free from the product page: for Windows as a setup or as a single program file (spherifyer.exe), for Linux (amd64) as a program file. The SHA-256 checksums are shown there too. On Windows, SmartScreen may ask before the first start, as the files are not signed yet.

With the setup (Windows)

A double-click on Spherifyer-Setup.exe is enough. Windows asks for administrator rights. The setup installs Spherifyer to C:\Program Files\Spherifyer, sets up the service, starts it and opens the dashboard in the browser. There the first-time setup leads through the admin password and the vCenter access. Afterwards the Start menu has an entry Spherifyer that opens the dashboard.

  • New version: run the setup of the new version. It stops the service, replaces only the program and starts it again. Settings and collected data stay. If the new version does not start, it restores the previous one. Running the same setup again replaces the program file (repair). It installs an older version only with --allow-downgrade.
  • Already installed by hand: if Spherifyer already runs as a service, for example from C:\Spherifyer, the setup updates that installation in place instead of adding a second one. It ends a Spherifyer in a console window from the same folder for that.
  • Uninstall: under Settings → Apps, Spherifyer. This removes the service and the whole program folder, including settings and collected data. Back up what you want to keep first (see Backup).
  • Rollout without a window, for example by software distribution, Intune or a startup script: Spherifyer-Setup.exe --silent (exit code 0 on success, 1 on an error). The log is spherifyer-setup.log in the program folder. Uninstall silently: "C:\Program Files\Spherifyer\spherifyer-setup.exe" --uninstall --silent.

Automatic updates work as without the setup (see Updates). Spherifyer updates the version shown under Apps itself.

Without the setup (Windows and Linux)

Put the program file into a folder of its own, for example C:\Program Files\Spherifyer or /opt/spherifyer. Everything Spherifyer creates ends up in this folder: settings, collected data and the encrypted password.

The first time, start Spherifyer by hand in a console window. It then asks for the access data of the vCenter (see Setup). If you start it as a service right away instead, it waits for the first-time setup in the browser.

Windows

cd "C:\Program Files\Spherifyer"
.\spherifyer.exe

Linux

cd /opt/spherifyer
./spherifyer

Run as a service

To keep Spherifyer running permanently, also after a restart of the server, set it up as a service. This needs administrator rights (sudo on Linux).

Windows

.\spherifyer.exe service install
.\spherifyer.exe service start

Linux

sudo ./spherifyer service install
sudo ./spherifyer service start

Should the service ever crash, Windows restarts it by itself.

You can also do this in the console window: Service tab (key 2), then i to set it up and s to start it. The console window has to be opened with administrator rights for this too.

The Service tab in the console window
The Service tab in the console window

Setup

On the very first start in a console window, Spherifyer asks three things (as a service, see First-time setup in the browser):

  1. the address of your vCenter (name or IP address),
  2. the user name,
  3. the password.

Spherifyer stores the password encrypted. It puts the key for it into a file of its own next to it (vsphere.key). Without this file the password cannot be read, so include it in your backups.

Spherifyer then collects the first data right away. Open the dashboard on the server in the browser at http://127.0.0.1:8080, or press o in the console window.

Most vCenters use a self-issued certificate. Spherifyer accepts this by default. If your vCenter has an official certificate, you can make the check stricter: set vcenter.insecure to false.

First-time setup in the browser

If Spherifyer starts for the first time without a console window, as a service (as after the setup) or with --no-tui, it creates a config.yaml and waits for the first-time setup in the browser at http://127.0.0.1:8080. It collects only after that.

The page asks for a new password for the local user admin (at least 8 characters, replacing the start password that would otherwise be generated) and for the vCenter: address, user, password and whether a self-signed certificate is accepted. Test the vCenter connection checks the values first. After Complete setup the dashboard starts without a restart, and you are signed in.

  • Only on the server itself: for security, Spherifyer accepts the first-time setup only through 127.0.0.1. Anyone opening it from another computer only sees this notice. It therefore does not work through a reverse proxy. On Linux without a browser on the server, an SSH tunnel helps: ssh -L 8080:127.0.0.1:8080 server, then open http://127.0.0.1:8080 on your own computer.
  • If only the vCenter password is missing, the page asks only for the vCenter, plus the current admin password, with the same lockout after failed attempts as the sign-in. With two-factor sign-in active, you then sign in with the code on the sign-in page.
  • In a container the page cannot be reached from the host. Set SPHERIFYER_VCENTER_SERVER, SPHERIFYER_VCENTER_USERNAME and SPHERIFYER_VCENTER_PASSWORD there. The page shows values from the environment read-only.
  • The audit log records the completion as First-time setup completed.

Access from other computers

At first, the dashboard can only be reached on the server itself. That way nobody gets to it from outside by accident. To open it from your workstation:

  • press l in the console window, or
  • set web.listen to 0.0.0.0:8080 and restart the service.

Also allow port 8080 in the server's firewall. You then reach the dashboard at http://<server name>:8080, with a certificate at https://<server name>:8080.

Spherifyer speaks HTTPS itself, on the same port. You add the certificate in the dashboard under Settings → HTTPS: as your own PEM files or automatically from Acmefyer, see Settings in the dashboard. Once a certificate is there, Spherifyer redirects requests over the network to HTTPS. Without a certificate the dashboard is not encrypted (HTTP). In that case only open it in a trusted network.

Port and proxy

Spherifyer takes over a proxy set up in Windows by itself: first the one from netsh winhttp show proxy, otherwise the proxy entered in the Internet Options. Exceptions like *.example.com are taken over too. Automatic detection and PAC scripts are not evaluated. You only need a proxy of your own if Windows does not know one or Spherifyer should use a different one.

You change the dashboard port and the proxy for the internet in the console window on the Settings tab (key 4):

  • Web port: for example 8443 instead of 8080. The address in front of it (local only or for everyone) stays as it is. If the port is already in use on the server, Spherifyer warns you.
  • Proxy URL: If the server needs a proxy for the internet, enter it here, for example http://10.10.75.1:8080. With a login: http://user:password@10.10.75.1:8080. Spherifyer stores the password encrypted in proxy.creds, not in config.yaml. Empty means: no proxy of its own, so the proxy from Windows or from HTTPS_PROXY applies.
  • Exceptions: names and networks that do not go through the proxy, separated by commas, for example example.com,10.20.0.0/16. The server itself, the private networks and your vCenter always connect directly.

Pick a field with the arrow keys and press Enter to change it. Enter accepts, Esc cancels. With t you check right away whether www.wedigo.net can be reached through the proxy you entered, even before saving. With s you save to config.yaml. The change takes effect after restarting Spherifyer or the service (spherifyer service restart).

Under In effect now, the tab also shows which proxy is in use right now and where it comes from (config.yaml, environment variable or Windows). If a value comes from an environment variable, you can only see it there (marked *read-only*), not change it.

The Settings tab in the console window: port, proxy and what is in effect
The Settings tab in the console window: port, proxy and what is in effect

Settings in the dashboard

You set the same and more in the dashboard: in the user menu at the top right under Settings. Choose the area on the left. The fields are on the right:

  • Software update and info (first): the installed version, the state of the update check with *Check now* and *Install now*, an *About Spherifyer* card with the note on the makers of Acmefyer, and below the update settings of config.yaml (mode, interval, maintenance window). The notes in the footer lead here too.
  • Web interface: port, whether the dashboard can be reached from this machine only or from the network, and after how much inactivity a sign-in ends.
  • Server: where config.yaml is, plus the paths of the database, the key, password, user and log files and whether the dashboard sign-in is on. You rarely change these. Move the files yourself first, otherwise Spherifyer starts without history, passwords or users. Only switch off the sign-in behind other protection.
  • HTTPS: whether the dashboard speaks HTTPS and with which certificate. It comes from your own files (certificate with chain and private key as PEM, applied right after saving) or from Acmefyer: enter address, enrollment token and agent CA fingerprint from Acmefyer (*Agents → Enrollment*) and click *Connect*. Spherifyer then appears in Acmefyer under Agents. There, add a deployment of type *Spherifyer* on the certificate for this server's name. Acmefyer issues, renews and delivers the certificate, Spherifyer switches without a restart. HTTP and HTTPS run on the same port. Requests over the network are redirected to HTTPS, requests on this machine (127.0.0.1) stay HTTP. *Disconnect* deletes the agent in Acmefyer, but the certificate stays in use.
  • vCenter: server, user, password and whether self-signed certificates are accepted. Spherifyer stores the password encrypted. Leave the field empty to keep the stored password. *Test the vCenter connection* signs in with the values entered, before you save.
  • Data collection: collection interval, collecting at start and how many days of history are kept.
  • Proxy: address, password and exceptions as in the console window, with a connection test to www.wedigo.net.
  • Admin account (only for the local user admin): *Change password* and two-factor authentication. *Set up two-factor* shows a QR code and the key for manual entry. Scan the QR code with an authenticator app (such as Microsoft or Google Authenticator) and confirm with the current code. From then on, the sign-in of admin also asks for the code from the app (field *Two-factor code*). The key is stored encrypted in the user file (auth.json, with the key file vcenter.key_file, which also encrypts the other passwords). If you change vcenter.key_file in the dashboard, it is re-encrypted with the new file. If the key file is lost or replaced, Spherifyer switches two-factor off (entry in the log and the audit log), and admin signs in with the password and sets it up again. If the phone is lost, delete the entries totp_secret and totp_enabled in auth.json. Then the password alone applies again.
  • AD/LDAP: in blocks as in Acmefyer: *Connection* (server, reader account, search base, *Test connection*), *Access* (group or OU per role, search while typing) and *Test sign-in*, see Sign-in with AD/LDAP. Applies at once.
  • Logging, Rightsizing and Planning: the values of the sections of the same name in config.yaml.

*Save* writes only the changed values to config.yaml. Comments and everything else stay as they are. The changes take effect after a restart: when Spherifyer runs as a service, *Restart now* restarts it and the dashboard reloads by itself. Otherwise quit Spherifyer in the console window with q and start it again. Until then the dialog marks the affected fields with *after restart*. Values from environment variables are shown with the variable's name and cannot be changed.

Login and password

On the first start, Spherifyer creates the user admin with a random initial password. The password is shown only once: in the console window on the Dashboard tab and in the log file spherifyer.log in the program folder.

  • After the first login, you choose your own password (at least 8 characters).
  • Later, change it in the user menu at the top right.
  • After several wrong attempts, Spherifyer waits a moment before it allows another try.

Forgot the password? Stop the service, delete the file auth.json in the program folder and start the service again. spherifyer.log then contains a new initial password.

Sign-in with AD/LDAP

Besides admin, your colleagues can sign in with their Windows account once you connect Active Directory or another LDAP server: in the user menu under Settings → AD/LDAP.

  1. Enter the server address (ldaps://dc01.corp.local:636 or ldap://…:389, optionally with StartTLS), a reader account with its password and the search base, for example DC=corp,DC=local. *Test connection* checks them with the values entered, before you save.
  2. Choose who gets which role. There are two: Admin may do everything admin may, Viewer sees everything and changes nothing (of the settings it sees only software update and info, without changing anything). For each role choose a group (also through nested groups in Active Directory) or an OU whose accounts get it. If both apply to an account, admin comes first. Type a name into the search field and take the hit with *Admin* or *Viewer*. For all other accounts choose *No access* (default) or *Viewer*.
  3. *Test sign-in* signs an account in on trial and shows which role it would get, why, and which groups it is in.
  4. *Save* applies at once, without a restart. Spherifyer stores the reader account's password encrypted in ldap.creds.

The local user admin keeps working, also while the directory cannot be reached. A directory account's password is changed in the directory, not in Spherifyer.

Audit log

What was changed in the dashboard is listed under Audit (admins only): sign-ins and failed attempts, password changes, AD/LDAP, settings, updates (the automatic ones too), restarts and collection runs started by hand, each with user and time, newest first. The list can be searched and filtered by area, user and period. The entries are kept in the Spherifyer database. The log file keeps recording the same events, there with the IP address as well.

Views

Storage: How full is each datastore, how much has been promised to the VMs, and how fast does it work? Including peak values of the last seven days, when it is expected to be full and which VMs have the highest latency on it. In the chart "Usage per datastore" the part Veeam uses is yellow: replica VMs (recognised by their "Restore Point …" snapshots) and Veeam's temporary backup and replication snapshots of other VMs. While a backup runs, a Veeam proxy attaches the disks of the VM it backs up (hot-add). vCenter then counts these disks twice in the provisioned space. That part is yellow at the end of the provisioned bar, red is only what is overcommitted without it, and the "overcommitted" warning leaves it out as well. Spherifyer recognises Veeam replicas by their restore points even when their name does not end in "_replica". "Hide replicas" hides them too.

Storage view
Storage view

VMs: All VMs in one table to filter and sort. A click on a row shows the network adapters and disks of the VM, and *Show history* opens its history. The filters find, for example, VMs connected to several networks or with a disconnected network adapter.

Hosts: Load of processor, memory and network per host, and which VMs run on it. Also, per host, the VMs that wait longest for free processor cores (CPU ready).

Topology: Your environment as a tree (vCenter, datacenter, cluster, hosts), and which VM is connected to which network (VLAN). With Simulate failure you fail hosts, clusters, datacenters or datastores with a click. A second click brings them back. To do this, show the datastores with *Show datastores*, or pick them under *Fail datastore …*. The drawing shows which VMs restart on another host of their cluster as with HA, which find no room and which stop with a failed datastore. VMs on local datastores fail with their host. If a whole site fails, its VMs start at another site as far as there is free RAM. Above it is a verdict with reasons, below it a table of the affected clusters.

Network topology
Network topology

Warnings: What Spherifyer notices, each with a recommendation, see Warnings and recommendations. The categories at the top filter the list, for example to Compliance (items from the vSphere Security Configuration Guide) or Capacity.

History: How usage has developed over a period of your choice. Plus who changed what in vCenter, and the network load of the hosts. Under *VMs*, the history of a single VM: CPU and RAM, the space it uses on the datastore, and the usage of each disk in the guest (via VMware Tools, a history vCenter does not show). CPU is the average and the peak since the previous collection, computed from vCenter's 20-second values, so short peaks between two collections are not missed. Spherifyer records storage every hour and, after 14 days, one value per day. Below, the VMs that grew most over the period.

History
History

Planning: Four views for the next decisions:

  • Forecast: Usage per cluster (CPU, RAM, storage, vCPU per core), whether the cluster absorbs a failure of its largest host, and when storage is full at the growth of the last 30 days. Below, all datastores by time to full. The time to full is also shown on the datastore cards in the Storage tab. Likewise the guest disks that grow measurably, with the day they are expected to be full.
  • Reclamation: VMs that have been off for a long time, idle VMs and snapshots older than 30 days, with the total storage, vCPUs and RAM. With monthly prices in the settings (planning.price_*), also the estimated saving.
  • What-if: A failure simulation as a map: hosts with their VMs, disaster examples (largest host, two hosts, half the cluster, maintenance host by host, datastore fails) or hosts of your choice. The VMs of failed hosts visibly move to the others, as HA would restart them. Whatever finds no room is shown under "Cannot start". Plus new VMs, a verdict with reasons, limits and how many VMs of that size still fit afterwards.
  • Licensing: How many processors and cores each datacenter has. You need this to plan your VMware licenses.

All views are available in German and English, light and dark.

Warnings and recommendations

After every collection, Spherifyer checks the data and reports what stands out, each with a suggestion what to do. In the dashboard, the placeholders in braces are replaced by real values.

Spherifyer rates CPU ready per vCPU, averaged over the last 5 minutes before the query: from 5 % it warns, from 10 % it is critical. vCenter reports the sum over all vCPUs of a VM. Spherifyer divides it by the number of vCPUs, also in the *Ready %* column of the VMs.

MessageRecommendation
If the largest host fails, the CPU of the other hosts is not enough: {pct}% loadAdd a host or spread the load so the cluster can absorb a failure.
If the largest host ({host} GB) fails, the RAM of the other {hosts} hosts is not enough: {pct}% usedAdd a host, add RAM or shrink or switch off VMs so the cluster can absorb a failure.
If the largest host ({host} GB) fails, the other hosts are {pct}% used in RAMWatch the reserve and add a host or RAM if it keeps growing.
CD/DVD drive is connectedDisconnect the drive when it is not needed, because connected media can block vMotion.
Emulated network adapter: {nics}Switch to vmxnet3: less CPU load and more throughput.
Virtual hardware {version} is outdated (recommended {min} or later)Upgrade the VM hardware in the next maintenance window (VM powered off, snapshot or backup first).
Lockdown mode is offTurn on lockdown mode (normal) so the host is managed through vCenter only.
No NTP server configuredAdd an NTP server and start the NTP service, because a wrong clock breaks sign-in, logs and certificates.
NTP service is not running (servers: {servers})Start the NTP service and set it to "Start and stop with host".
No timeout for ESXi Shell sessions (UserVars.ESXiShellInteractiveTimeOut = 0)Set a timeout, for example 900 seconds.
No syslog target configured (Syslog.global.logHost)Send the logs to a central syslog server so they survive a reboot.
CPU ready time {pct}% per vCPU – vCPU scheduling heavily delayedMigrate VMs to less loaded hosts or reduce the number of vCPUs.
CPU ready time {pct}% per vCPU – host CPU possibly overloadedCheck the host CPU load, consider DRS balancing or VM migration.
CPU topology set manually: {vcpu} vCPUs, {cores} cores/socket ({sockets} sockets)Reset the CPU topology to automatic unless licensing or operating system requirements call for it.
Drive {path}: only {pct}% free ({free} GB free / {cap} GB total)Clean up the drive or expand capacity right away.
Drive {path}: {pct}% free ({free} GB free / {cap} GB total) – threshold: 10%Clean up the drive or plan capacity.
Expected to be full in {days} days – grows by {growth} GB per day, {free} TB still freeCheck the growth (Planning, Reclamation) and add capacity or move VMs in time.
High I/O latency: read {read} ms / write {write} msCheck the storage array, analyze queue depth and I/O contention.
Elevated I/O latency: read {read} ms / write {write} msMonitor the I/O load on the datastore.
Datastore {pct}% provisioned – overcommit ({prov} TB on {cap} TB capacity)Check thin-provisioned VMs, snapshots or clones and clean up if needed.
Datastore {pct}% used ({used} TB / {cap} TB)Migrate VMs or expand capacity.
Datastore {pct}% used ({used} TB / {cap} TB)Monitor usage and plan capacity if needed.
{n} active VMs on one datastoreIf it keeps growing, spread VMs across more datastores.
{n} active VMs on one datastore (recommended: max. 20)Spread VMs across several datastores to avoid I/O bottlenecks.
CPU load at {pct}%Keep an eye on the CPU load.
CPU load at {pct}%Migrate VMs to other hosts or consider a hardware upgrade.
RAM usage critical: {pct}% used ({used} GB / {total} GB)Migrate VMs to other hosts or add physical RAM.
RAM usage elevated: {pct}% used ({used} GB / {total} GB)Monitor RAM usage and rebalance VMs if needed.
vCPU overcommit {ratio} : 1 ({vcpu} vCPUs on {logical} logical cores)Rebalance VMs under high CPU load.
vCPU overcommit {ratio} : 1 ({vcpu} vCPUs on {logical} logical cores)Spread VMs across more hosts or add CPU resources.
{ratio} virtual CPUs per physical core ({vcpu} vCPUs / {cores} cores) – threshold: 4Spread VMs across more hosts or add CPU resources.
ESXi Shell running on the hostDisable the ESXi Shell once administrative work is done.
SSH service running on the ESXi hostDisable SSH once administrative work is done.
Memory ballooning active: {mb} MB – ESXi is reclaiming memory from the guest OS (memory pressure on the host)Check host RAM usage in the Hosts tab. If ballooning persists: move VMs to hosts with more free RAM.
VM is swapping {mb} MB – ESXi has swapped memory pages to disk (the host is or was under memory pressure)Check host RAM usage in the Hosts tab. If the host is relaxed, the value disappears with the next VM restart. If swapping persists: rebalance VMs or add host RAM.
High CPU usage: avg {avg}% / P95 {p95}% over {n} samples ({days} days) – VM has {vcpu} vCPUsAssign more vCPUs or spread the workload across more VMs.
Low CPU usage: avg {avg}% / P95 {p95}% over {n} samples ({days} days), CPU ready P95 {ready}% per vCPU – VM has {vcpu} vCPUsReduce the number of vCPUs, but not below {min} – surplus vCPUs add scheduling overhead on the host.
High RAM usage: avg {avg}% / P95 {p95}% over {n} samples ({days} days) – VM has {gb} GBAssign more RAM or spread the workload.
Low active RAM: avg {avg}% / P95 {p95}% over {n} samples ({days} days) – VM has {gb} GB, host {host}% usedFirst check the usage inside the guest (Task Manager, for SQL Server "max server memory"), then reduce the RAM, but not below {min} GB.
Snapshot '{name}' present – age: {age} days (created: {date})Review the snapshot and remove it if possible. Old snapshots can use a lot of storage and slow down the VM.
VMware Tools not installedInstall VMware Tools for complete monitoring and best performance.
VMware Tools not running (installed but not started)Restart the VM or start VMware Tools manually.
VMware Tools outdatedUpdate VMware Tools to the current version.
Inconsistent folder name: VM name "{name}" ≠ folder "{folder}"Rename the folder so that VM name and folder match.
VM is powered off (power state: {state})Check whether the VM is still needed. Remove or archive VMs that are not.

Free, no license

Spherifyer is free: no license key, no license check and no limits. You see your whole environment with all hosts, VMs and datastores, including their history, in the dashboard, in the console window and through the interface.

Spherifyer comes from the makers of Acmefyer. You find the note in the dashboard footer and under Settings → Software update and info.

If you entered a license key before, there is nothing to do: Spherifyer keeps starting with your existing config.yaml and database. It ignores the license section in config.yaml and the environment variables SPHERIFYER_LICENSE_*, so you can delete them.

Updates

Spherifyer keeps itself up to date. It regularly checks www.wedigo.net for a new version, makes sure it really comes from us, and installs it.

How this works is set in update.mode:

  • auto (default): new versions are installed, the service briefly restarts afterwards.
  • notify: Spherifyer only reports a new version. You install it yourself in the dashboard.
  • off: no checks for updates.

With update.window you set a time of day when installing is allowed, for example "02:00-05:00". The dashboard shows the state under Settings → Software update and info, where you can also check and install by hand.

Automatic installs only happen when Spherifyer runs as a service and may write to its program folder. When started by hand in a console window, it only reports new versions.

Spherifyer also looks for a new major version such as 2.0 at every check and installs it like any update. Spherifyer is free, so a new major version costs nothing.

Back to the previous version

Spherifyer keeps the previous version. If a new version does not start properly, it goes back to the old one by itself. The failed version is then set aside, so rollback cannot bring it back: it reports that the previous version is already installed. You can also go back by hand:

Windows

.\spherifyer.exe rollback
.\spherifyer.exe service restart

Linux

sudo ./spherifyer rollback
sudo ./spherifyer service restart

Backup

Back up the program folder. These files matter:

  • config.yaml: your settings
  • vsphere.key and vsphere.creds: the password for the vCenter. The two belong together.
  • proxy.creds: the password for the proxy, if you entered one. It can only be read together with vsphere.key.
  • auth.json: the users of the dashboard
  • history.db: the collected data, the audit log and the connection to Acmefyer. Safest to copy while the service is stopped.

To restore, put the files back into the program folder and start the service.

Troubleshooting

Spherifyer cannot reach the vCenter. Check that the server reaches the vCenter under the name you entered and that no firewall blocks port 443. What exactly goes wrong is shown in the console window (Logs tab, key 3) or in spherifyer.log.

The event log in the console window
The event log in the console window

The dashboard only works on the server itself. That is the default. See Access from other computers.

I can no longer log in to the dashboard. See Forgot the password.

Performance values are missing under Storage. The vCenter only delivers these values after a while. They appear after the first collections. Performance statistics must be switched on in vCenter, which they normally are.

An update is not installed. Does Spherifyer run as a service, and may it write to its folder? A version that has been rolled back once is not installed again.

Updates: no connection. Updates need a connection to www.wedigo.net (HTTPS, port 443). Settings → Software update and info and spherifyer.log show the exact error. In the console window, the Settings tab shows which proxy is in use. If a proxy is set up in Windows (netsh winhttp show proxy or Internet Options), Spherifyer uses it by itself. If the server needs a different proxy or Windows does not know one, enter it on the Settings tab, check it with t and save it with s. Then restart Spherifyer or the service. See Port and proxy. Without the console window, enter the proxy in config.yaml under proxy.url. The environment variable HTTPS_PROXY still works too.

If none of this helps, write to us using the contact form.

Look up

This part is for looking things up when you want to change a particular setting.

Settings

The settings are in the file config.yaml in the program folder. You change most of them in the dashboard under Settings, all of them with a text editor. After a change, restart the service. Instead, you can also set each value with an environment variable. The variable's name is below the setting in the table.

Key / environment variableDefaultMeaning
vcenter.serverSPHERIFYER_VCENTER_SERVER–Address of your vCenter (name or IP address).
vcenter.usernameSPHERIFYER_VCENTER_USERNAME–User in vCenter, for example spherifyer@vsphere.local. The Read-only role is enough.
vcenter.passwordSPHERIFYER_VCENTER_PASSWORD–Normally stays empty, because the password is stored encrypted. Only enter it here as a last resort.
vcenter.insecureSPHERIFYER_VCENTER_INSECUREfalseAlso accept self-issued vCenter certificates.
vcenter.key_fileSPHERIFYER_VCENTER_KEY_FILEvsphere.keyFile with the key for the stored password.
vcenter.creds_fileSPHERIFYER_VCENTER_CREDS_FILEvsphere.credsFile with the encrypted password.
collection.intervalSPHERIFYER_COLLECTION_INTERVAL1hHow often Spherifyer asks the vCenter, for example 30m (30 minutes) or 1h (1 hour).
collection.run_on_startSPHERIFYER_COLLECTION_RUN_ON_STARTtrueCollect the first data right after the start.
web.listenSPHERIFYER_WEB_LISTEN127.0.0.1:8080Address at which the dashboard can be reached. 0.0.0.0:8080 opens it to other computers.
web.tls_certSPHERIFYER_WEB_TLS_CERT–Certificate for HTTPS with chain (PEM). Empty: no own certificate. A certificate from Acmefyer then goes to spherifyer-tls.crt next to config.yaml.
web.tls_keySPHERIFYER_WEB_TLS_KEY–Private key of the certificate (PEM). Set both or leave both empty.
storage.pathSPHERIFYER_STORAGE_PATHhistory.dbFile that holds the collected data.
storage.retention_daysSPHERIFYER_STORAGE_RETENTION_DAYS90How many days the data is kept. 0 means forever.
log.levelSPHERIFYER_LOG_LEVELinfoHow detailed the log file is: debug (very detailed), info, warn or error (errors only).
log.formatSPHERIFYER_LOG_FORMATtextLayout of the log file: text for reading, json for analysis tools.
log.fileSPHERIFYER_LOG_FILE–Name of the log file. Empty: spherifyer.log in the program folder. On Linux as a service the log then goes to the system log (journalctl).
auth.enabledSPHERIFYER_AUTH_ENABLEDtrueLogin for the dashboard. Only switch off in isolated networks.
auth.fileSPHERIFYER_AUTH_FILEauth.jsonFile with the users of the dashboard.
auth.session_ttlSPHERIFYER_AUTH_SESSION_TTL12hAfter how long without activity you have to log in again.
update.modeSPHERIFYER_UPDATE_MODEautoauto, notify or off, see Updates.
update.intervalSPHERIFYER_UPDATE_INTERVAL6hHow often to look for updates.
update.windowSPHERIFYER_UPDATE_WINDOW–Time of day when updates may be installed, for example "02:00-05:00". Empty: any time.
proxy.urlSPHERIFYER_PROXY_URL–Proxy for the internet (updates), for example http://10.10.75.1:8080, also with user@. The password is kept encrypted in proxy.creds_file. Empty: no proxy of its own, so HTTPS_PROXY and NO_PROXY or the proxy from Windows apply. The vCenter never goes through the proxy.
proxy.no_proxySPHERIFYER_PROXY_NO_PROXY–What should not go through the proxy, separated by commas: names, domains like example.com, IP addresses or networks like 10.20.0.0/16. The server itself, the private networks and the vCenter are always excluded.
proxy.creds_fileSPHERIFYER_PROXY_CREDS_FILEproxy.credsFile with the encrypted password for the proxy. Spherifyer creates it when you save a proxy with a password in the console window. A password you write into proxy.url by hand is moved there at the next start.
rightsizing.min_vcpuSPHERIFYER_RIGHTSIZING_MIN_VCPU2Rightsizing never suggests shrinking a VM below this many vCPUs. Applies to all systems except Windows.
rightsizing.min_memory_gbSPHERIFYER_RIGHTSIZING_MIN_MEMORY_GB2Rightsizing never suggests shrinking a VM below this much RAM (GB). Applies to all systems except Windows.
rightsizing.windows_min_vcpuSPHERIFYER_RIGHTSIZING_WINDOWS_MIN_VCPU4Like rightsizing.min_vcpu, for Windows VMs.
rightsizing.windows_min_memory_gbSPHERIFYER_RIGHTSIZING_WINDOWS_MIN_MEMORY_GB8Like rightsizing.min_memory_gb, for Windows 11, Windows Server 2022 and later. Spherifyer takes the system reported by VMware Tools, otherwise the type set in vCenter.
rightsizing.windows_legacy_min_memory_gbSPHERIFYER_RIGHTSIZING_WINDOWS_LEGACY_MIN_MEMORY_GB4Like rightsizing.min_memory_gb, for older Windows versions.
rightsizing.cpu_ready_pctSPHERIFYER_RIGHTSIZING_CPU_READY_PCT2Spherifyer only suggests fewer vCPUs if the VM shows this much CPU ready per vCPU over 7 days (P95, in percent), so it really has to wait for free cores. 0: regardless of CPU ready.
rightsizing.host_memory_pctSPHERIFYER_RIGHTSIZING_HOST_MEMORY_PCT75Spherifyer only suggests less RAM if the VM's host is used at least this much (percent). On a free host, less RAM gains nothing. 0: regardless of the host.
planning.price_vcpuSPHERIFYER_PLANNING_PRICE_VCPU0Monthly price per vCPU for the estimated saving in Reclamation. 0: no amounts.
planning.price_memory_gbSPHERIFYER_PLANNING_PRICE_MEMORY_GB0Monthly price per GB of RAM.
planning.price_storage_tbSPHERIFYER_PLANNING_PRICE_STORAGE_TB0Monthly price per TB of storage.
planning.currencySPHERIFYER_PLANNING_CURRENCYEURCurrency of the prices, for example EUR or CHF.
planning.off_daysSPHERIFYER_PLANNING_OFF_DAYS30Powered-off VMs show up in Reclamation after this many days.
planning.idle_daysSPHERIFYER_PLANNING_IDLE_DAYS14Idle VMs (CPU never above 200 MHz, hardly any network traffic) show up in Reclamation after this many days.
planning.full_soon_daysSPHERIFYER_PLANNING_FULL_SOON_DAYS90Warn when a datastore is expected to be full within this many days at the current growth.
ldap.urlSPHERIFYER_LDAP_URL–Address of the directory for sign-in with AD/LDAP: ldaps://server:636 or ldap://server:389. Empty: only the local user admin.
ldap.start_tlsSPHERIFYER_LDAP_START_TLSfalseEncrypt an ldap:// connection with StartTLS.
ldap.insecure_skip_verifySPHERIFYER_LDAP_INSECURE_SKIP_VERIFYfalseDo not verify the directory server's certificate. For tests only.
ldap.bind_dnSPHERIFYER_LDAP_BIND_DN–Reader account Spherifyer searches users with, for example CN=svc-spherifyer,OU=Service,DC=corp,DC=local.
ldap.bind_passwordSPHERIFYER_LDAP_BIND_PASSWORD–Password of the reader account, only as a stopgap or from the environment. Entered in the dashboard, it is stored encrypted in ldap.creds_file.
ldap.base_dnSPHERIFYER_LDAP_BASE_DN–Search base for users, groups and OUs, for example DC=corp,DC=local.
ldap.user_filterSPHERIFYER_LDAP_USER_FILTER–Search filter for the sign-in name, %s stands for the name. Empty: Active Directory (sAMAccountName).
ldap.admin_groupSPHERIFYER_LDAP_ADMIN_GROUP–DN of the group or OU whose accounts are admins (may do everything admin may).
ldap.viewer_groupSPHERIFYER_LDAP_VIEWER_GROUP–DN of the group or OU whose accounts are viewers (see everything, change nothing).
ldap.default_roleSPHERIFYER_LDAP_DEFAULT_ROLE–What all other accounts from the directory get: none (no access, also when empty) or viewer. At least one group or OU, or viewer, is required once ldap.url is set.
ldap.creds_fileSPHERIFYER_LDAP_CREDS_FILEldap.credsFile with the reader account's encrypted password (key: vcenter.key_file).

Commands

Enter these commands in a console window in the program folder.

Option / commandDefaultMeaning
spherifyer -configconfig.yamlUse a different settings file.
spherifyer -no-tui–Start without the text interface.
spherifyer -version–Show the version number.
spherifyer service install–Set up as a service (with administrator rights).
spherifyer service uninstall–Remove the service again.
spherifyer service start–Start the service.
spherifyer service stop–Stop the service.
spherifyer service restart–Restart the service.
spherifyer service status–Show whether the service is running.
spherifyer rollback–Go back to the version before the last update. Restart the service afterwards.

Keys in the console window

KeyMeaning
1–4, ←/→, TabSwitch between the Dashboard, Service, Logs and Settings tabs.
rCollect new data right away.
oOpen the dashboard in the browser.
lOpen the dashboard to other computers, or close it again.
i / u / s / xSet up, remove, start or stop the service (Service tab, with administrator rights).
k / jScroll through the log (Logs tab).
↑/↓, Enter, EscOn the Settings tab: pick a field (arrow keys), change it (Enter), accept (Enter) or cancel (Esc).
sOn the Settings tab: save port and proxy to config.yaml. Takes effect after a restart.
tOn the Settings tab: check whether www.wedigo.net can be reached through the proxy you entered.
q, Esc, Ctrl+CQuit Spherifyer.

Interface for your own analyses

You can also fetch all data of the dashboard as JSON, for example for your own scripts or monitoring systems. Except for the addresses marked as public, you have to be logged in for this (POST /api/auth/login). Error messages are in English. With the header Accept-Language: de they come in German, as in the dashboard.

RouteLoginMeaning
GET /healthpublicAnswers as long as Spherifyer is running. Useful for monitoring systems.
GET /api/infopublicName and version.
POST /api/auth/loginpublicLog in with user and password.
POST /api/auth/logoutpublicLog out.
GET /api/auth/mepublicWho is logged in.
GET /api/auth/statuspublicWhether the login is switched on and whether the initial password is still in use.
POST /api/auth/passwordpublicChange the password.
/api/reportrequiredAll current data. Each warning has a severity (Critical, Warning or Info), an English category such as Capacity or Guest-Storage, and a code with args for the text.
/api/statusrequiredWhen data was last and will next be collected, whether a collection is running, and the last error.
/api/licensesrequiredLicense requirements per datacenter.
/api/history/totalsrequiredHistory of the total usage, ?days=30.
/api/history/datastorerequiredHistory of one datastore, ?name=…&days=30.
/api/history/all-datastoresrequiredHistory of all datastores, ?days=30.
/api/history/host-netrequiredNetwork history of one host, ?name=…&days=180.
/api/history/vmrequiredHistory of one VM (CPU, RAM, usage on the datastore, guest disks), ?name=…&days=30.
/api/history/vm-growthrequiredStorage growth of all VMs over the period, ?days=30.
/api/datastoresrequiredNames of all datastores.
/api/hostsrequiredNames of all hosts.
/api/user-actionsrequiredWho changed what in vCenter, ?days=180.
/api/refreshrequiredCollect new data right away.
/api/debug/ds-perfrequiredHelps us troubleshoot when performance values are missing.
/api/host-net-snapshotrequiredCurrent network load of all hosts.
GET /api/updaterequiredState of the updates.
POST /api/update/checkrequiredLook for updates now.
POST /api/update/installrequiredInstall an available update.
GET /api/settingsrequiredThe settings from config.yaml including environment variables, without passwords, and which of them apply only after a restart.
POST /api/settingsrequiredSave settings: {"changes":{"collection.interval":"30m"}}, passwords separately as vcenterPassword and proxyPassword. Values from environment variables cannot be changed this way.
POST /api/settings/testrequiredCheck signing in to the vCenter ({"target":"vcenter",…}) or the connection to www.wedigo.net through a proxy ({"target":"proxy",…}) with values not saved yet.
POST /api/settings/restartrequiredRestart the service so that saved settings apply. Only when Spherifyer runs as a service.
POST /api/settings/ldap/testrequiredCheck connection, reader account and search base of the directory with values not saved yet.
POST /api/settings/ldap/groupsrequiredSearch groups and OUs in the directory (query) for choosing the access.
POST /api/settings/ldap/checkrequiredSign an account in on trial (user, userPassword) and show whether it would get access. Creates no session.
GET /api/account/2farequiredWhether two-factor is on for the local user.
POST /api/account/2fa/setuprequiredCreate a new key (not active yet). Returns the key and QR code (SVG).
POST /api/account/2fa/enablerequiredTurn it on with a code from the app (code).
POST /api/account/2fa/disablerequiredTurn it off and delete the key.
GET /api/httpsrequiredState of HTTPS: the loaded certificate (subject, names, issuer, expiry), files, load error and the connection to Acmefyer.
POST /api/https/acmefyerrequiredConnect to Acmefyer (server, token, fingerprint): enrolls Spherifyer as an agent. Administrators only.
DELETE /api/https/acmefyerrequiredDisconnect from Acmefyer. Acmefyer deletes the agent, but the certificate stays in use.
GET /api/auditrequiredThe audit log, newest first (actor, period = 24h, 7d or 30d), with all users for the filter. Admins only.