Setting Up WSL for Secure Redis CLI Connections to Azure Redis Cache on Windows.
Published May 22 2024 07:55 AM 1,199 Views


This blog post is a comprehensive guide to setting up the Windows Subsystem for Linux (WSL) on your Windows machine. This enables you to use the Redis Command-Line Interface (CLI) to connect to an Azure Redis Cache instance securely. By running a Linux environment on Windows, you can use Redis CLI without the need for a separate virtual machine or dual booting.


Methods to Connect to Redis As of the date of this blog post, there are several ways to connect to Redis:

  • Redis Insight: A graphical interface offering insights and connectivity troubleshooting for Redis data.
  • Redis CLI: A command-line tool for direct interaction with Redis.
  • Client Libraries: Connection via libraries available for various programming languages.


Redis Insight

For those interested in a GUI-based approach, our blog post on using Redis Insight for Azure Cache for Redis provides in-depth information. Redis Insight is the best option for those who prefer a GUI with high-level connectivity troubleshooting and insights into our data present in the cache.


Redis CLI

Redis CLI (Command-Line Interface), on the other hand, is ideal for those who prefer command-line familiarity, ability to use scripting and automation capabilities in a lightweight and portable environment or have restrictions on installing third-party software.


In addition, Redis CLI is a powerful tool for interacting with Azure Cache for Redis as a client. It allows you to directly communicate with your Redis instance, making it useful for debugging, troubleshooting, and managing your cache. 


Redis CLI and Secure Connections Historically


In the past, Redis CLI was limited to non-TLS ports, which posed a security concern for Azure Redis Cache connectivity. Secure connections required workarounds like disabling SSL-only configurations, connect through the Azure Console, or employ utilities like Stunnel for SSL connections, and while the default remains a plain TCP connection, the introduction of SSL/TLS connections has now made it possible to secure your Redis CLI connection without compromising security.



Installing WSL on Windows To use Redis CLI on Windows


The Redis-CLI runs natively on Linux, making its installation/usage process very straightforward. For Windows environments, we must install the Windows Subsystem for Linux (WSL) to be able to run Linux tools directly on Windows.  


In this blog post, we'll install WSL using the default Ubuntu distribution of Linux. However, you can change this default by adding "--distribution" to the WSL command and specifying the desired Linux distribution (a list of available distributions can be obtained with "wsl --list --online").


We'll use WSL version 2, which is the default at the time of this post. However, specific scenarios or exceptions may warrant switching to WSL 1. Microsoft documentation provides a table to help you decide which version is better suited to your needs:




Comparing WSL Versions | Microsoft Learn 


Step #1: Install WSL in Windows.



For Windows 10 (version 2004 and higher) / Windows 11:


  • WSL can be installed with a single command through PowerShell or the Windows CMD in administrator model: “wsl --install".
  • Optional parameters for distribution change and online installation are available.
  • To install WSL 1 instead of WSL 2, use: “wsl --install --enable-wsl1”.


Link: Basic commands for WSL | Microsoft Learn 


For Windows Server 2022,


  • WSL installation is supported using the same command: “wsl --install".
  • Execute the command in an administrator PowerShell or Command Prompt.
  • Restart your machine after installation.


For Windows Server 2019 (version 1709+):


  • WSL needs to be manually enabled.
  • Use PowerShell to enable WSL:
    “Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux”



Step #2: Choose a Linux Distribution



After enabling WSL and rebooting the computer, you must choose a Linux distribution to install, you can see a list of available distributions here.


Now that the Linux distribution has been downloaded, extract and install the selected Linux distribution using the following PowerShell commands:


extract the <DistributionName>.appx package's contents

“Rename-Item .\Ubuntu.appx .\”

“Expand-Archive .\ .\Ubuntu”


--Navigate to the folder containing the download and run the following command in that directory, where app-name is the name of the Linux distribution .appx file.--

“Add-AppxPackage .\app_name.appx”


Note: If you encounter an error code 0x8007007e, your system does not support WSL. Please refer to the Microsoft documentation for comparing WSL versions to decide if WSL 1 or WSL 2 is better suited for your needs.


Step #3: Add the Linux Distribution to Windows Environment PATH



Add the Linux distribution to your Windows environment PATH using the following steps:


  • Open PowerShell or Command Prompt as an administrator.
  • Execute the following commands to add the Linux distribution to the PATH:


$userenv = [System.Environment]::GetEnvironmentVariable("Path", "User") 

[System.Environment]::SetEnvironmentVariable("PATH", $userenv + ";C:\Users\Administrator\Ubuntu", "User") 


Previous Windows Versions 


For older versions of Windows:


Previous Windows Server Versions 

  • WSL is not supported on older versions of Windows Server. 


Note: During any of the WSL installations, you will be prompted to enter a username and a password at the end of this. Make sure to keep them somewhere you remember. 




Using Redis CLI


After installing WSL and a Linux distribution, update and install Redis with the following commands from your Linux VM:  


“sudo apt-get update”





Afterwards, run: 


“sudo apt-get install redis” 




Check the Redis status within your Linux distribution, Ubuntu: 




You can validate the Redis CLI Version installed with “redis-cli --version"





Note: If you run into any issues, try restarting the service by running “sudo systemctl restart redis.service” 


Retrieve your Azure Cache for Redis access keys from the Azure Portal's settings/authentication section.


Remember to keep these keys confidential.


Gather the access information to your Azure Cache for Redis from the Azure Portal by navigating to the settings/Authentication blade, please note that the access keys to your Azure Cache are extremely sensitive information that should never be shared, and example is only shown due to the test cache already being deleted by the time this blog is published.





For this example, I will connect using TLS by running the following command including the --tls parameter: 


“redis-cli.exe -p 6380 -h -a YourAccessKey --tls” 


Note: For alternatives on how gather your cache information, please refer to the following documentation: Use redis-cli with Azure Cache for Redis - Azure Cache for Redis | Microsoft Learn 


Verify the connection with the PING command:




The PONG reply will let you know you have successfully connected to your Azure Cache for Redis instance using the redis-cli. 


With an established connection, you can now insert keys, run commands in a loop, perform mass data insertion and more. Please reference to the Redis documentation for a full rundown of the capabilities of the Redis CLI console.




This blog post has outlined the steps necessary to set up WSL and securely connect to Azure Redis Cache using Redis CLI. For further details and troubleshooting, please refer to the official Microsoft documentation on using redis-cli with Azure Cache for Redis. You can find the current information at the Azure Cache for Redis development FAQ.


1 Comment
Version history
Last update:
‎May 22 2024 07:54 AM
Updated by: