PowerShell tile

About using PowerShell in SquaredUp DS

You can use PowerShell to visualize data from external tools and data sources directly in your SquaredUp DS dashboards. The PowerShell feature consists of three components:

  1. PowerShell tiles contain the individual PowerShell script for the tile.

    A PowerShell tile can be added to any of your dashboards. Each PowerShell tile consists of a PowerShell Run As account, an optional PowerShell profile, and a script that is inserted within the tile.

    Since the script in the tile isn't encrypted you shouldn't store any sensitive data like passwords in a PowerShell tile.

    Only administrators can add script to a PowerShell tile. Users who can edit tiles due to their Team Folder permissions can see the script, but they will get an error message when they try to save changes (for more information about security measures for users trying to edit sensitive tiles see Signing and security for sensitive tiles).

    Jump to How to configure a PowerShell tile
  2. PowerShell profiles contain re-usable scripts with encrypted sensitive data.

    A PowerShell profile is created once and then can be re-used in PowerShell tiles. Only administrators can create PowerShell profiles. Since PowerShell profile scripts are encrypted and can only be seen by administrators, you can safely store scripts that contain credentials, authentication tokens, etc. You can also load external modules in a profile (e.g. a VMWare module downloaded from the internet).

    You can also use PowerShell profiles for more sophisticated code, for example if your tile needs to combine data from two different API connections, you can put credentials for both connections in the profile. Make sure to give your profile a meaningful description to remember which provider(s) the profile connects to and what it does with the data.

    SquaredUp DS users who can edit tiles due to their Team Folder permissions can use PowerShell profiles in their PowerShell tiles, but they can’t see the underlying script.

    Jump to How to configure a PowerShell profile
  3. PowerShell Run As accounts contain the credentials that define the permissions deciding how PowerShell scripts are run (both the script in the tile and the profile script chosen for the tile).

    The PowerShell Run As account Default comes with every SquaredUp DS installation and uses the SquaredUp DS app pool identity to run the scripts. Since running PowerShell scripts within the SquaredUp DS application pool process can pose a security risk and affect SquaredUp DS performance, you can change the default Run As to use a different account.

    You can also add new Run As accounts to be able to execute scripts with different credentials.

    Jump to Managing PowerShell Run As accounts

Required PowerShell version

Using PowerShell in SquaredUp DS requires PowerShell version 5.1 and above. If you want to use .NET Core PowerShell scripts, you need to have .NET Core 6.0 installed.

If you are using HA, make sure .NET Core is installed on all HA machines. If you configured a tile to use the NET core option and try to view the tile on a HA machine that doesn't have .NET Core installed, the tile will display the error message "PowerShell host process returned errors: A fatal error occurred. The required library hostfxr.dll could not be found."

When do you use a PowerShell tile?

Since PowerShell tiles contain any PowerShell script you want, there are a lot of different use cases for them. Here are some examples:

If you're looking for some real-life examples of dashboards, check out the Dashboard Gallery. You'll find dashboards that users from SquaredUp and the Community have created to help you get the most out of SquaredUp DS:

Dashboard Gallery

How to configure a PowerShell tile

  1. Add a new tile to a dashboard and click on Integrations > PowerShell.
  2. Choose the visualization for your PowerShell tile:

  3. Scope:
    Select the scope for your tile (optional).

  4. Environment:
    Run As
    Choose the Run As account you want to use for running the profile and the script in this tile. Choosing a Run As is mandatory. If you haven't configured any Run As accounts, the tile will use the Default Run As.
    Note: If you click on add new, you can create a new Run As in a new tab. Click on reload after you created the new Run As to be able to choose it from the drop-down.
    Profile
    If you want to use a PowerShell profile for this tile, choose the profile (optional).
    Note: If you click on add new, you can create a new profile in a new tab. Click on reload after you created the new profile to be able to choose it from the drop-down.
    Advanced
    Execution environment:

    Choose the execution environment your PowerShell script was intended for to make sure it gets executed correctly:

    • Windows PowerShell (.NET framework)
    • PowerShell (.NET Core)

    Note:

    The .NET Core option is only available if it is installed on your server, .NET Core is not automatically installed with SquaredUp DS.

    Note:

    If you are using HA, make sure .NET Core is installed on all HA machines. If you configured a tile to use the NET core option and try to view the tile on a HA machine that doesn't have .NET Core installed, the tile will display the error message "PowerShell host process returned errors: A fatal error occurred. The required library hostfxr.dll could not be found."

    Interval:

    The interval enables you to limit how often a script gets executed in SquaredUp DS. For example, you might want to run a script less frequently if it makes a request to an API that charges you per request or an API that puts a limit on how many requests you can make within a time period.

    How does the interval affect how often PowerShell scripts are run in SquaredUp DS?

    By default, a PowerShell script will be executed every time the dashboard refreshes (every minute). If you set the interval to 10 mins, you create a 10 min cache for your script results and your script won't run until the last fetched results are 10 mins old.

    The interval is not a schedule, it does not trigger a script execution every 10 mins. Scripts will only be executed when the dashboard is reloaded and the results in the cache are older than the interval (10 mins in this example). The cache is valid for all users, which means if another user opens the same dashboard in SquaredUp DS or via Open Access and the script has been executed 5 mins ago, they see the cached results immediately but have to wait for 5 mins to see fresh results.

    Can multiple tiles share the same cache?

    Identical tiles share the same cache. For tiles to be considered identical, the JSON code of both tiles needs to be identical. If you want to use identical tiles to reduce the load on the back-end, you can copy the JSON from one tile and paste it into a different tile.
    The shared cache works across your whole SquaredUp DS instance on:

    • All dashboards (including Open Access dashboards), as long as they use the same page timeframe
    • Perspectives for the same object on the same drill-down using the same page timeframe
    Timeout:

    You can control when the script will run into a timeout. By default, scripts will be aborted after 1 min. You can define a longer timeout for long running scripts.

    Best practice:

    Even if you can use long running scripts by setting the timeout to several minutes, you shouldn't use scripts that run for a long time. Long running scripts lead to tiles that show a loading spinner for minutes and are not user-friendly.

    Tip:

    Instead of setting the timeout for scripts to a longer time, run the script outside of SquaredUp DS periodically, and store the results in a CSV file. Create a PowerShell tile that accesses and visualizes the results in the CSV file.

  5. Script:
    Insert the PowerShell script you want to use. You can view your script's response data in the next step.
    Click next.
  6. Response data:
    Here you can check if your script works and returns the expected data.
  7. Configure the settings for the visualization you chose:
  8. Click done to save the tile.
    The tile now shows data according to your script.

How to configure a PowerShell profile

  1. From the top right hand menu ☰ click system.
  2. Go to the PowerShell tab.
  3. Click add new profile.
  4. Enter a name and a description for the new profile.
  5. Enter the profile script.
  6. Click add profile.
    The profile is now saved and can be used in a PowerShell tile.

When do you need to re-enter PowerShell profiles?

Encrypted information like providers, PowerShell profiles, and Run As accounts can get lost when you change SquaredUp DS's application pool identity.

Make sure that you are able to recreate the information after you changed the app pool identity, for example by storing them temporarily in a safe place.

Managing PowerShell Run As accounts

PowerShell scripts are very powerful and can cause damage when not properly configured. Your Run As accounts contain the credentials a script uses to run as, which means the Run As determines the permissions a PowerShell script has when it is executed. When you are creating Run As accounts, you want to give your PowerShell scripts the minimum permissions needed so that they can do what you intended for them to do without giving them permissions that can be exploited and could lead to security risks.

Best practices for Run As accounts:

1) For all Run As accounts: Use a service account, not a user account for Run As accounts.

Do not use your own or anyone's personal user account for Run As accounts. Instead, create a new account that is not used by a specific person (a "service account"), but only used for running PowerShell scripts. Consider the permissions of this service account carefully.

Required permissions for service accounts:

The service account you use for Run As must have at least the following permission:

  • Allow log on locally

2) We strongly recommend you change the Default Run As account to the credentials you want to use as the default Run As.

Every PowerShell tile needs a Run As and if you haven't created a Run As yet, tiles will use the Default Run As. The Default Run As uses the SquaredUp DS app pool to run scripts. The SquaredUp DS app pool account might grant too many permissions that are not needed for your scripts and can potentially damage your system, which is why using this default account is not recommended. Create a service account that you want to use for the Default Run As and change the Default Run As to use those credentials.

3) Consider disabling the option to use the SquaredUp DS app pool for the Default Run As.

To make sure that the SquaredUp DS app pool can't be used after you changed the Default Run As, you can disable the option to use the SquaredUp DS App pool.

4) Consider creating different service accounts for running different scripts, depending on what their purpose is and what permissions they need. Save each service account as a different Run As account in SquaredUp DS.

When do you need to re-enter Run As accounts?

Encrypted information like providers, PowerShell profiles, and Run As accounts can get lost when you change SquaredUp DS's application pool identity.

Make sure that you are able to recreate the information after you changed the app pool identity, for example by storing them temporarily in a safe place.

How to disable the PowerShell feature

By default, the PowerShell feature is available, but SquaredUp DS administrators can globally disable it. When the feature is disabled, any existing PowerShell tiles will still be visible to users as before but the scripts won't be executed anymore. Instead, PowerShell tiles will display the error message "PowerShell functionality is disabled". Administrators will still be able to create and edit PowerShell tiles, profiles and Run As accounts.

On the SquaredUp server, run Notepad as administrator (StartRun, type notepad, and then right-click and select Run as administrator).

In Notepad, open the security.json file from the SquaredUp DS folder:

...\User\Configuration\security.json

If the file doesn't exist, create it by following these steps and saving the file as security.json at the end.


  1. Edit the JSON file to contain the following property:
    {
        "enable-powershell-execution": false
    }

    If the file already contains settings, then you will need to add a comma at the end of the previous line.
  2. Save the JSON file.
  3. Recycle the SquaredUp DS application pool.
    The PowerShell feature is now disabled. Scripts in existing PowerShell tiles won't be executed anymore.

Tips for your PowerShell scripts

Troubleshooting

Was this article helpful?


Have more questions or facing an issue?