geturl command — LAMMPS documentation

\(\renewcommand{\AA}{\text{Å}}\)

# geturl command

## Syntax

    geturl url keyword args ...

- url = URL of the file to download

- zero or more keyword argument pairs may be provided

- keyword = output or overwrite or timeout or verify or verbose

      output filename = write to filename instead of inferring the name from the URL
      overwrite yes/no = if yes overwrite the output file in case it exists, do not if no
      timeout time = stop download if not completed within given time in seconds
      verify yes/no = verify SSL certificate and hostname if yes, do not if no
      verbose yes/no = if yes write verbose debug output from libcurl to screen, do not if no

## Examples

    geturl https://www.ctcms.nist.gov/potentials/Download/1990--Ackland-G-J-Vitek-V--Cu/2/Cu2.eam.fs
    geturl https://github.com/lammps/lammps/blob/develop/bench/in.lj output in.bench-lj

## Description

Added in version 29Aug2024.

Download a file from an URL to the local disk. This is implemented with the libcurl library which supports a large variety of protocols including “http”, “https”, “ftp”, “scp”, “sftp”, “file”. The transfer will only be performed on MPI rank 0.

The output keyword can be used to set the filename. By default, the last part of the URL is used.

The overwrite keyword determines whether a file should be overwritten if it already exists. If the argument is no, then the download will be skipped if the file exists.

The timeout keyword can be used to modify the timeout for downloads in seconds. After the timeout, the download will stop, even if incomplete. The default time value is 300, i.e. 5 minutes. Setting the timeout to 0 means to wait forever.

The verify keyword determines whether `libcurl` will validate the SSL certificate and hostname for encrypted connections. Turning this off may be required when using a proxy or connecting to a server with a self-signed SSL certificate.

The verbose keyword determines whether a detailed protocol of the steps performed by libcurl is written to the screen. Using the argument yes can be used to debug connection issues when the geturl command does not behave as expected. If the argument is no, geturl will operate silently and only report the error status number provided by libcurl, in case of a failure.

Using geturl with proxies for http or https

The libcurl library supports routing traffic through proxies by setting suitable environment variables (e.g. `http_proxy` or `https_proxy`) as required by some institutional or corporate security protocols. In that case you probably also want to use the verify no setting.

Using a proxy may also be needed if you are running on an HPC cluster where only the login or head nodes have access to the internet, but not the compute nodes. In this case the following input can be adapted and used for your local HPC environment:

    variable headnode getenv PBS_O_HOST     # use SLURM_SUBMIT_HOST when using SLURM instead of Torque/PBS
    shell ssh -N -f -D 8001 ${headnode}     # start SOCKS5 proxy with backgrounded ssh connection to cluster head node
    shell putenv http_proxy=socks5://localhost:8001 https_proxy=socks5://localhost:8001
    geturl https://download.lammps.org/tars/SHA256SUMS # download a file using proxy
    shell head SHA256SUMS                # check if the download was successful

## Restrictions

This command is part of the EXTRA-COMMAND package. It is only enabled if LAMMPS was built with that package. See the Build package page for more info. It also requires that LAMMPS was built with support for the libcurl library. See the page about Compiling LAMMPS with libcurl support for further info. If support for libcurl is not included, using geturl will trigger an error.

## Related commands

shell

## Default

overwrite = yes, timeout = 300, verify = yes, verbose = no