Spherifyer documentation

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 and the license.

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.

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 and the license. 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

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).

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

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).

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

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.

Setup

On the very first start, Spherifyer asks three things in the console window:

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.

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.

The dashboard itself is not encrypted (HTTP). If it should be reachable across a larger network, put a web server with HTTPS in front of it, for example IIS or nginx.

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 Einstellungen (settings) tab (key 4):

• Port der Weboberfläche (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; then the proxy from Windows or from HTTPS_PROXY applies.
• Ausnahmen (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).

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, not change it.

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 and in the log file spherifyer.log in the program folder.

• After the first login, you choose your own password (at least 10 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.

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.

VMs: All VMs in one table to filter and sort. A click on a row shows the network adapters and disks of the VM. 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, and which VM is connected to which network (VLAN).

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.

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; it is also shown on the datastore cards in the Storage tab.
• 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.

License and activation

Without a license key, Spherifyer shows a single host so you can try the program. With a license key you see your whole environment.

• You receive the license key by e-mail right after the purchase. It belongs to the e-mail address you bought with.
• Activation needs a connection from the server to www.wedigo.net, also through a proxy (see Port and proxy). After that, Spherifyer checks in there briefly every 30 days. If the connection fails, the license keeps working for up to 60 days.
• A license covers one installation and all updates of the version you bought, for example all 1.x versions. When a new major version comes out, Spherifyer points it out but does not install it by itself.

Which host without a license? Spherifyer picks it at random at the first collection and sticks with it. It only picks another one if the host no longer exists in vCenter. You see this host with its VMs and datastores in all views. The dashboard only counts the other hosts ("7 more hosts – visible with a license key"). All data is still collected: as soon as the license is valid, you see your whole environment, including its history.

Entering the license key: In the dashboard, open the user menu at the top right and choose *License*. Paste the key, enter the e-mail address you bought with and click *Save*. Spherifyer checks the key online right away and writes it to config.yaml. You can also enter it there yourself (license.key and license.email, see Settings) and restart the service.

The *License* dialog shows who the license is for, which version it covers, when it was last checked and until when it is valid. *Check now* asks right away, for example after you have allowed the connection to www.wedigo.net.

Moving to another server: Enter the key on the new server. The license then moves there, and the old server shows only one host again. To get the license back, click *Transfer the license to this installation* there.

If there is a problem with the license, the dashboard shows a notice at the top: when www.wedigo.net has not been reached for more than 45 days, the license was moved to another server, revoked or has run out, or the server's clock is behind. Spherifyer keeps running in every case, and no data is lost.

More on purchase and refunds: Pricing and License terms.

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 in the user menu under *Software update*, 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.

Updates always stay within your major version, for example 1.x. When a new major version comes out, Spherifyer shows a notice below the header, in *Software update*, with the license and in the console window: your license is not valid for the new major version, it needs an upgrade. Your version keeps receiving updates. You can dismiss the notice below the header; it returns with the next major version.

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. You can also do this by hand:

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

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 and the state of the license on this server. 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 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.

License/updates: no connection. The license and updates need a connection to www.wedigo.net (HTTPS, port 443). The *License* dialog in the user menu and spherifyer.log show the exact error. In the console window, the Einstellungen (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 Einstellungen 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. Open it with a text editor. After a change, restart the service. Instead, you can also set each value with an environment variable; its name is below the setting in the table. The license key and e-mail address can also be read from a file, for example a Docker secret: add _FILE to the name and give the path of the file, for example SPHERIFYER_LICENSE_KEY_FILE=/run/secrets/spherifyer_license.

Commands

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

Keys in the console window

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). Without a license the interface returns the same as the dashboard, that is only the one visible host with its VMs and datastores.