The Mirror is the new SAS Depot (and much more)

8 Likes

With SAS Viya 3.4 comes "Mirror Manager" which significantly eases the build and use of local packages repositories, aka "Mirrors." In this article, I will try to convince you to always plan, build and use a Mirror as part of your SAS Viya installation and also give you some cool tips with Mirror Manager.

As a reminder, during the deployment of SAS Viya, the ansible playbook instructs the machines, that are part of the deployment, to download the SAS packages (RPMs or MSI) from the "internet facing" SAS Hosted repository servers.

This "mirror" term refers to the fact that we are building a copy of the original SAS Packages Repository. Then the deployment can download the SAS packages from this copied repository instead of using the SAS Hosted one.

I remember the time when I was downloading the SAS 9 Depot on my USB Hard Drive, before visiting a customer for a deployment. You know...just in case he had forgotten to download it in preparation of our meeting... As the guy in charge of the installation I liked to have this security.

Do you miss that? Don’t worry ... you can still do it with Mirror Manager.

ALWAYS Build a mirror - why?

Here are some of reasons why you should build and use a mirror:

The usage of a mirror is required, anyway in several cases.

when there is no internet access on the SAS Viya deployment machines
for SAS Viya deployment in SUSE Linux environments
for Multi-Tenancy or multiple CAS Servers

Using a mirror allows you to reinstall the exactly same version of the packages.
Using a local repository reduces the security risk exposure of Internet access.
You can build it anywhere!

One of the target machine of the deployment
A shared File or Web Server at customer site,
Your own laptop, etc...

And on any kind of operating system: Windows, Linux and even Mac.

ALWAYS Build a mirror - how?

With SAS Viya 3.4 and Mirror Manager it is now, very simple to build and use a mirror.

Step 1 - Build it

All the things you need to build your mirror are:

The deployment data zip file from the Software Order email (typically: SAS_Viya_deployment_data.zip)
Mirror Manager utility that you can freely download.
A machine (can be your laptop or one of the servers you plan to install) with enough disk space.

See documentation

Once you have downloaded and unzipped Mirror Manager on your local machine or server, open a shell (DOS or Linux bash depending on your host operating system) and run Mirror Manager utility to ensure it is working, for example:

C:\MirroMgr>mirrormgr help

Mirror manager is a command line utility and can do many things, through 4 types of commands:

Click any image to see a larger version.

The most interesting command for us, though is "mirror". This command is the one we use to build our own mirror of the SAS Packages repository.

The "--help" option of the command gives us more details on how to use it :

So, for example if we want to build a mirror for our SAS Viya order, all we need is to specify the deployment data zip file (SAS_Deployment_data.zip) that was attached the Software Order email:

C:\MirrorMgr>mirrormgr mirror --deployment-data 3.4se18w30\SAS_Viya_deployment_data_18w30.zip

If we do that Mirror Manager starts to create the local repository in the user's home directory (C:\users\frarpo in my case). However, we might not have enough space there to store a repository. Depending on the type of order, the size of the repository (containing all the packages for your ordered product) can vary from 13 to 50 or more GBs.

So, it is much better to specify an alternate location where you've made sure that you had enough space (your USB Hard drive for example).

C:\MirrorMgr>mirrormgr mirror --deployment-data 3.4se18w30\SAS_Viya_deployment_data_18w30.zip --path "e:\Repo34se18w30\"

But hold on ... what will be exactly downloaded if I do that?

Well, mirrormgr will download all the packages corresponding to your order but for all types of available platform – it means: RedHat, SUSE and potentially others in the future.

So, we likely don’t need to have the SAS packages for any type of platform, right?

Fortunately, we have the "list remote" command that can help here, it lists the available options:

C:\MirrorMgrTests>mirrormgr.exe list remote platforms --deployment-data 3.4se18w47/SAS_Viya_deployment_data_18w47.zip
x64-redhat-linux-6
x64-redhat-linux-7
x64-suse-linux-12

However, don’t get confused by the number at the end, it is not the Linux version.

Use x64-redhat-linux-6 for SAS Viya deployment on all supported versions of Red Hat Enterprise Linux and its equivalent such as Oracle Linux.
Use x64-suse-linux-12 for SAS Viya deployment on all supported versions of SUSE Linux.

Don't use x64-redhat-linux-7 as it refers to something different (docker repository).

So finally, the command you need to run is:

C:\MirrorMgr>mirrormgr mirror --deployment-data 3.4se18w30\SAS_Viya_deployment_data_18w30.zip --path "e:\Repo34se18w30\" --platform x64-redhat-linux-6 --latest

Note: we add the "--latest" option to ensure that Mirror Manager download the latest verions of the SAS packages (including the Hotfixes)

Now, we can see that Mirror Manager is starting to download the packages from the SAS Hosted repository:

Mirroring 1/2 repos/shipped/va/104/va-104-x64_redhat_linux_6-yum
 118.44 MiB / 13.53 GiB [>-------------------------------------------------------------------]   0.91% 1.09 MiB/s 3h27m5s

So what do we get at the end? Well, we get an organized structure that contains the SAS software packages themselves (RPMs or MSI or other depending on your products) and some associated metadata files.

See below an example of the mirror repository content and structure:

Step 2 - Serve it

Once the download is complete, you need to make your mirror (or rather your local package repository) available for the machines where you plan to deploy SAS Viya.

The cool thing is that you can archive and move the content of your newly created "repo" directory wherever you want.

Then there are multiple methods to make it available for the deployment:

Copy it everywhere (on all SAS Viya target machines)
NFS-Mount it everywhere (on all SAS Viya target machines)
Serve it over http or https

The principle of the local repository is to have a single location for the packages, that all the SAS Viya target server can access to download the packages that they need. So usually we want to make this location available through an HTTP server or through the file system (A shared file system is used when we have multiple machines in the deployment).

Step 3 - Use it

The last thing to do is to ensure that the deployment playbook will use our brand new local mirror as its package repository.

All the SAS Viya target hosts need to be able to access the mirror location, but thanks to Ansible, we only have one file to edit to set the location: vars.yml.

So before running the ansible deployment playbook, check the value of REPOSITORY_WAREHOUSE in your vars.yml, and replace the default value with the location of your local mirror.

REPOSITORY_WAREHOUSE: "https://ses.sas.download/ses/"

We can see that by default the access to the repository is done through https (because the communication with our SAS Hosted repository server must be secured) but it can also be done through standard HTTP or even File system access like:

REPOSITORY_WAREHOUSE: "http://sasviya01.race.sas.com:8123/"

REPOSITORY_WAREHOUSE: "file:/nas/dept/mis/viya/sas_repos/test/"

REPOSITORY_WAREHOUSE: "file:///c:/sasinstall/mirrorViyaWindows18w47" (for windows deployment)

Or

REPOSITORY_WAREHOUSE: "file:/sasinstall/mirror18w47"

See RFC for examples of file URI.

But remember that the repository warehouse URL must be available to all hosts that participate in the deployment since the hosts are going to use that address to retrieve packages from the repositories. For example, if the repository warehouse is file-based, then that location should be shared across hosts and should be shared at the same path on each of those hosts.

You can stop your reading here unless you’d like to know more and learn some tips.

There are many useful things that you can do with the mirror manager. Let's review them quickly.

Tip 1 - Build a mirror from another mirror

By default, the Mirror Manager tries to download the packages from the SAS Hosted repository (typically "http://ses.sas.download"). However, using the "url" option, you can direct the Mirror manager to build the local mirror from another mirror.

It can be very useful for lockdown customer environments where a "jumphost" or "bastion" is used to get the packages, but cannot be directly accessed by the machines participating in the SAS Viya deployment.

The diagram below illustrates this use case:

Example:

c:\viya34tmp>mirrormgr mirror --deployment-data C:\viya34tmp\SAS_Viya_deployment_data.zip --path C:\viya34tmp\MyRepo --platform x64-redhat-linux-6 --latest --insecure --url "https://gelweb.race.sas.com/mirror/09MYXC/"

Note: if your serverA, in the scenario above, only has access to Internet through an HTTP or HTTPS proxy, mirror manager can deal with it. See the official documentation.

Tip 2 - Check the mirror integrity

Mirror Manager has a "verify" command that you can use to check your mirror repository content. "Verify" checks the package hash in the repository metadata against the file on disk, verifying that the packages on disk have not be tampered with and are all present. Note that you need to ensure to use the same latest and platform flags when running verify against the mirror as when it was created.

Example:

c:\MirrorMgrTests>mirrormgr.exe verify --path "3.4se18w30/myRepo34se18w30"
Verifying 1/2 repos\shipped\va\104\va-104-x64_redhat_linux_6-yum
 13.53 GiB / 13.53 GiB [=====================================================================] 100.00% 441.28 MiB/s 31s
Verifying 2/2 sasmd\shipped\va\104\va-104-x64_redhat_linux_6-yumsasmd
 2.28 MiB / 2.28 MiB [=========================================================================] 100.00% 44.92 MiB/s 0s
Repository repos\shipped\va\104\va-104-x64_redhat_linux_6-yum: verified
Repository sasmd\shipped\va\104\va-104-x64_redhat_linux_6-yumsasmd: verified

Tip 3 - Use Diff to see the new packages

Now, you are interested by a potential software update and you’d like to see if your mirror could be refreshed to benefit from the latest packages. Mirror Manager can help you!

You can use the "mirror diff" command:

mirrormgr mirror diff --deployment-data path-to-deployment-zip-file-from-SOE 
--path path-to-mirror-destination --latest

Let's see an example:

C:\MirrorMgrTests>mirrormgr mirror diff --deployment-data 3.4se18w30\SAS_Viya_deployment_data_18w30.zip --path 3.4se18w30\myRepo34se18w30\ --latest --platform x64-redhat-linux-6
Starting diff process
Diffing 1/4 repos/shipped/va/100/va-100-x64_suse_linux_12-yum
Diffing 2/4 repos/shipped/va/104/va-104-x64_redhat_linux_6-yum
Diffing 3/4 sasmd/shipped/va/100/va-100-x64_suse_linux_12-yumsasmd
Diffing 4/4 sasmd/shipped/va/104/va-104-x64_redhat_linux_6-yumsasmd
Done
Repository sasmd/shipped/va/104/va-104-x64_redhat_linux_6-yumsasmd: no new packages found
Repository repos/shipped/va/100/va-100-x64_suse_linux_12-yum: new packages found
New package: sas-tkmtrb1-01.12.00-20180711.230148391635.suse.x86_64.rpm
New package: sas-baseui1-03.13.00-20180711.211149548837.suse.x86_64.rpm
New package: sas-tkspdsdrv1-03.13.00-20180711.231639760650.suse.x86_64.rpm
New package: sas-tkair-03.13.00-20180711.233006399589.suse.x86_64.rpm
New package: sas-relationships-3.6.16-20180613.1528913768264.suse.x86_64.rpm
New package: sas-tkgraph2-03.13.00-20180711.224145354350.suse.x86_64.rpm
...
<more and more lines>
...
New package: sas-cpp-birdprint6-6.1.105646-20180905.1536177913.sad
New package: sas-certframe-3.1.46-20180625.1529949596423.sad
New package: sas-licenses-cli-1.4.7-20180603.1528064123282.sad
New package: sas-tkfnc1-03.13.00-20180711.223804780708.sad
New package: sas-compsrvcfg-03.11.00-20180711.212231034110.sad
New package: sas-crsmtpsrvc-01.13.00-20180711.220101186130.sad
New package: sas-tklauncher1-01.13.00-20180711.225810925646.sad
New package: sas-rabbitmq-server-3.7.3-20180515.1526408034975.sad
New package: sas-tsmodel1-03.13.00-20180711.232208269444.sad
New package: sas-tkqc1-03.13.00-20180711.230820989006.sad
New package: sas-backup-agent-2.1.29-20180612.1528836411326.sad
New package: sas-grodscrendr1-3.9.0-20180711.232222463982.sad
New package: sas-themecontent-1.1.62-20180711.1531289140877.sad
New package: sas-tkaacas-03.13.00-20180711.232854757131.sad
New package: sas-audit-cli-1.5.0-20180601.1527863137426.sad
New package: sas-crsstat-01.13.00-20180711.223739333395.sad
New package: sas-casluaclnt-01.13.00-20180711.210139577646.sad
New package: sas-crsfcmpact-01.13.00-20180711.214312253840.sad
New package: sas-tkaccess1-03.13.00-20180711.222916806727.sad
New package: sas-tkstat1-03.13.00-20180711.231715741134.sad
New package: sas-ygforcast-1.13.0-20180711.232941482699.sad
New package: sas-cpp-commons6-6.1.105646-20180905.1536177913.sad
New package: sas-transformations-2.4.53-20180615.1529111481300.sad
New package: sas-crossdomainproxy-1.3.2-20180619.1529398991726.sad
New package: sas-orchestration-cli-1.1.42-20180816.1534448442316.sad
New package: sas-jobexecapp-2.1.20-20180612.1528837342703.sad
New package: sas-search-2.1.37-20180613.1528914066291.sad
New package: sas-tkdmine1-03.13.00-20180711.223458429223.sad
New package: sas-jobexecution-2.4.22-20180615.1529092031764.sad
New package: sas-tkhps1-03.13.00-20180711.224743011776.sad
New package: sas-docconvjars-1.0.12-20180525.1527279525342.sad
New package: sas-securedom-03.13.00-20180711.231147153078.sad
New package: sas-tkspde1-03.13.00-20180711.231448585680.sad
New package: sas-qkbs-cli-1.3.3-20180603.1528065858373.sad

That's a very long list! And I'm surprised because I'm using an order that I created yesterday, so I should not have many new packages, right? (It might change in the future but AFAIK SAS RnD hasn’t yet fully implemented the "continuous delivery" approach with several updates within a day.)

Okay, so if we have a better look we now see that there is some extra information that we don't really care about: we see the "suse" packages (even if we filtered with the platform type) and also, we see the "sad" files which are not very relevant as we are only interested in the new packages.

This issue might have been fixed in the more recent version of mirror manager. Otherwhise what we can do is "kind of" filtering the output using "grep -v" or "findstr /v" to exclude lines that are matching "sad" or "suse" pattern - as in the example below.

C:\MirrorMgrTests>mirrormgr mirror diff --deployment-data 3.4se18w30\SAS_Viya_deployment_data_18w30.zip --path 3.4se18w30\myRepo34se18w30\ --latest --platform x64-redhat-linux-6 | findstr /R /v "suse sad" > newpackages.txt

Once you know what the new RPMs are, you can decide (in prevision of a software update of your deployment) to "refresh" your mirror : synchronize it with the SAS repository in preparation of an update of your deployment, with a command like:

C:\MirrorMgrTests>mirrormgr mirror --deployment-data 3.4se18w30\SAS_Viya_deployment_data_18w30.zip --path 3.4se18w30\myRepo34se18w30\ --latest

As explained in the updating your SAS Viya software section of the official deployment guide.

Tip 4 - Check the Mirror Manager logs

You have problems using Mirror Manager? But you don’t see any logs? Mirror Manager like all the nice tools logs your actions. By default, the logs are stored in the user application folders.

For the linux version of mirror manager it is $HOME/.local/share/mirrormgr
For the windows version of mirror manager it is %LOCALAPPDATA%\\mirrormgr

Tip 5 - Use the customer existing mirror

You might have noticed this comment in the vars.yml for the repository-warehouse variable:

#
# If the SAS packages are already available to the server (e.g. through a RHN satellite channel),
# set this variable to "none" to indicate no additional repository is needed for deployment.
REPOSITORY_WAREHOUSE: "https://ses.sas.download/ses/"

A very interesting thing with SAS Viya 3.4 is that: if your customer has found a way to make the SAS packages available for the target machines into his existing corporate package repository, you can configure REPOSITORY_WAREHOUSE to make your deployment rely on the customer's repository (instead of using a specific one just for SAS packages).

Tip 6 - Get the deployment playbook from the mirror

As you know (if you deployed SAS Viya at least once), one of the very first step of your deployment is to generate the installation playbook corresponding to your software order.

That is the purpose of the SAS orchestration CLI: it uses your Software Deployment data file (SAS_Viya_Deployment_data.zip) as an input to retrieve some deployment data from the SAS Hosted server and build the playbook locally.

But actually, instead of contacting the SAS Hosted server, you now have an option to instruct the orchestration CLI to use your local mirror instead! So now you can do that even if you are not connected to Internet! Here is an example:

.\sas-orchestration build --input c:\sas\install\SAS_Viya_deployment_data.zip 
--repository-warehouse file:///sas_repos

The cool thing: it also automatically inserts the mirror location value in the vars.yml that is inside your playbook! So you don’t even have to change it – when you run the deployment playbook the target machines directly download the packages from the mirror that you used to build the playbook.

Conclusion

Okay, that's it! I hope I convinced you. Now just do it! Plan the mirror in your architecture designs, build it, and use it!

Big thanks to Eliott Peel and Erwan Granger for their contributions to this post.

Alexandr · ‎12-24-2019

Very useful article