1. The Sage Virtual Machine

This page describes how to use the Sage appliance that you can download from http://www.sagemath.org/download-windows.html.

1.1. Requirements

The Sage appliance (packaged virtual machine) can be used on any operating system that supports the free VirtualBox player, for example Microsoft Windows. Your computer must have at least 2.5 GB (!) of free disk space and at least 512 MB of RAM. The virtual machine can also be used with other hypervisors like VMware. However, unless you are already familiar with VMware, we recommend that you use VirtualBox. In our experience, it is easier for non-technical users.

1.2. Installation

  1. Download VirtualBox (available at http://www.virtualbox.org/wiki/Downloads). Install it anywhere you want. Version 4 or later is required.

  2. Download the file sage-x.y.z.ova (for example, sage-4.7.2.ova) from http://www.sagemath.org/download-windows.html (select the location nearest to you).

    Sage webpage download

  3. Open VirtualBox. Your screen should look like this:

    1openvbox.JPG

  4. Import sage-x.y.z.ova by clicking File, then Import Appliance:

    2import.JPG

  5. You should see an Appliance Import Wizard window open:

    3import_wizard.JPG

  6. Import the Sage appliance by clicking Choose then browsing for the file sage-x.y.z.ova downloaded earlier. Select the file and click Next.

  7. It is recommended that you accept the settings that appear on the next window by clicking Finish:

    4wizard_settings.JPG

  8. The import will now begin. You should see a progress window:

    5importing_progress.JPG

  9. Once the import is complete, your VirtualBox manager should now look like one of the following images:

    6manager_after_import.JPG

    7manager_after_import_alt.JPG

  10. If you want to enable shared folders between Sage and your Windows system, complete the following steps (you can skip this for now and come back to it later you want to enable shared folders):

    1. In the running VirtualBox window, click Devices, then Shared Folders:

      8shared_folders.JPG

    2. Click on the icon with a green + in the upper right corner:

      9shared_folders.jpg

    3. Under Folder Path, browse to select the path of the Windows folder that you want to share using the pull-down menu and selecting Other:

      10shared_folders.JPG

    4. Check Auto-mount and Make Permanent. Click OK, then click OK again.

    5. From the menu, select Machine, then Reset:

      align="center"

    The files will be in /media/sf_<volume name>.

1.3. Using the Sage Notebook

  1. Start VirtualBox.

  2. To start the Sage notebook server, power on Sage-x.y.z by selecting it and clicking 'Start'. (This may take awhile. You may see some warning messages you can safely ignore.)
  3. You may see an Information window explaining how to integrate the mouse pointer with the virtual machine: {{attachment:12mouse_pointer.JPG}

  4. Wait a few moments until the running VirtualBox window displays a message saying Open your web browser to ...:

    13localhost.JPG

    Open your web broswer (it's best to use Firefox or Chrome) and go to the address http://localhost:8000. The following page should appear:

    Empty Sage notebook

  5. If you would like other users to be able to create additional accounts on the same local virtual machine, you will first need to complete some further steps. See the advanced options section below.
  6. When you are finished working with Sage, close your browser

    as usual (it is not necessary to Sign Out). In the running VirtualBox window, click Machine, then Close:

    15close.JPG

    Select Send the shutdown signal then click OK:

    16close.JPG

    The running window will closed automatically, and then you may close VirtualBox.

1.4. Using the Sage shell

  1. Start VirtualBox if you have not already done so.

  2. Power on sage-x.y.z (if you have not already done so) by selecting it and clicking Start.

  3. Once the virtual machine is powered on, press Ctrl C to quit the Sage notebook.

  4. Type
    ./sage
    on the command line to start a shell interface in Sage.
  5. To work with files attached in a shared folder (if you have shared folders enabled), type
    attach /media/sf_<volume name>/filename
    in the Sage command line session.

1.5. Troubleshooting

2. Advanced Options

2.1. Changing the keyboard layout

To temporarily change the keyboard layout (for example, French AZERTY), you can drop to the shell and run the command

sudo loadkeys azerty

To make this change permanent, you have to edit a configuration file. Run

sudo nano /etc/sysconfig/keyboard

and set it to the following:

KEYTABLE="fr-latin1"
MODEL="pc105+inet"
LAYOUT="fr"

2.2. Giving Others Access to the Sage Virtual Machine

You can run the Sage appliance as a server on the network, so that others can access it similar to http://www.sagenb.org. In this case, you have to make some changes to the virtual machine such that not everybody can log in.

  1. Log into the virtual machine as root: In the virtual machine, press Alt-F1, log in as user root with password sage. See the advanced options section for more details.

  2. Once you are logged in as root, change the password for both the root and sage user account:
    [root@sage ~]# passwd root
    Changing password for user root.
    Retype new password: 
    passwd: all authentication tokens updated successfully.
    [root@sage ~]# passwd sage
    Changing password for user sage.
    Retype new password: 
    passwd: all authentication tokens updated successfully.
  3. Now switch to the sage account. You can either log in as sage with the new password, or type
    [root@sage ~]# su sage
    [sage@sage root]$ cd
    [sage@sage ~]$
  4. Configure the notebook server to start in a secure mode. For this, you have to edit the .bash_profile file in the sage account. For example, type

    [sage@sage ~]$ nano .bash_profile
    and replace the line
    ./sage -notebook interface=\'\' port=8000 open_viewer=False require_login=False
    with
    ./sage -notebook interface=\'\' port=8000 open_viewer=False require_login=True secure=True

    Then press Ctrl X to exit, and y when nano asks you to save the file before exiting (save it again as .bash_profile).

  5. Now reboot the virtual appliance:
    [sage@sage ~]$ exit
    exit
    [root@sage ~]# reboot
  6. Upon the reboot, Sage will ask for some further information. You will find the following in the VirtualBox window:

    ----------------------------------------------------------------------
    | Sage Version ..., Release Date: ...                                |
    | Type notebook() for the GUI, and license() for information.        |
    ----------------------------------------------------------------------
    
    Please wait while the Sage Notebook server starts...
    ...
    notebook(interface=r'''''''',port=8000,open_viewer=False,require_login=True,secure=True)
    The notebook files are stored in: sage_notebook.sagenb
    In order to use an SECURE encrypted notebook, you must first run notebook.setup().
    Now running notebook.setup()
    Domain name [localhost]: 
    Simply press return to use the default domain name. A SSL cryptographic key is then automatic created with this hostname.
  7. Now set up an admin password for the Sage notebook server. Unless you have set up such an account previously, Sage will ask you for a password automatically:
    Please choose a new password for the Sage Notebook 'admin' user.
    Do _not_ choose a stupid password, since anybody who could guess your password
    and connect to your machine could access or delete your files.
    NOTE: Only the md5 hash of the password you type is stored by Sage.
    You can change your password by typing notebook(reset=True).
    
    Enter new password: 
    Please enter a new password following the instructions.
  8. Optional: Once your Sage server is secured, you can make it accessible from the network. For this, you have to stop the virtual machine (not just suspend it). Then, in the VirtualBox window, go to Settings -> Network -> Adapter 1. It does say Attached to: NAT. Switch it to Bridged Adapter. Click OK and restart the virtual machine. Note: This makes your virtual machine accessible from the network. Only perform this step after you have changed passwords and configured the notebook server to be secure, as described above.

  9. Optional: Give the Sage virtual machine more resources, so it can server more clients. Go to Settings -> System. On the Motherboard tab, increase Base Memory to about half of the physical ram of your host computer. On the Processor tab, increase the number of processors to your host CPU number of cores. Finally, on the Acceleration tab, enable VT-x/AMD-V if your CPU supports this.

To connect to the Sage server, you have to use https://... instead of http://.... For example, on the host computer where the virtual machine is running, the Sage server listens at https://localhost:8000. Since our SSL key is not signed by a certificate authority (which you can do, but it does cost money) web browsers will show a warning that the authority of the key cannot be verified. While a signed SSL key would provide a higher level of security, the network data between the browser and the Sage server is nevertheless encrypted.

2.3. How to become a Sage developer

Some Unix familiarity is assumed below. If you've never used anything but Windows, some of this won't make sense.

  1. Change to the $SAGE_ROOT directory:

    [sage@localhost directory]$ cd
    [sage@localhost ~]$ cd sage
    [sage@localhost sage]$ 
  2. To actually edit files, you'll perhaps want to install the editor of your choice. For example, to install Emacs do this:
    [sage@localhost sage]$ sudo yum install emacs
    The nano editor is included.
  3. Now type, for example,
    [sage@localhost sage]$ cd devel/sage/sage/rings/
    [sage@localhost rings]$ emacs arith.py
    or
    [sage@localhost rings]$ nano arith.py
    and edit the file to your heart's content.
  4. Save the file and type sage -br to build the changes and install them:

    [sage@localhost rings]$ cd
    [sage@localhost ~]$ cd sage
    [sage@localhost sage]$ sage -br
    ----------------------------------------------------------
    sage: Building and installing modified SAGE library files.
    ...
    ----------------------------------------------------------------------
    | SAGE Version x.y.z, Release Date: .........