% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/htc-config.R
\name{htc_config}
\alias{htc_config}
\title{Configure a connection to an HTC submit server}
\usage{
htc_config(username = NULL, server = NULL, path = ".", overwrite = FALSE)
}
\arguments{
\item{username}{A character string. Your HTC username (NetID), e.g.
\code{"erwin.lares"}. If \code{NULL} and no \code{htc.cfg} exists, the function
prompts interactively.}

\item{server}{A character string. The HTC submit server hostname.
Defaults to \code{"ap2002.chtc.wisc.edu"}. If \code{NULL} and no \code{htc.cfg}
exists, the function prompts interactively.}

\item{path}{A character string. Directory where \code{htc.cfg} will be
read from or written to. Defaults to \code{"."} (current working
directory).}

\item{overwrite}{Logical. If \code{TRUE}, recreates \code{htc.cfg} even if one
already exists. Defaults to \code{FALSE}.}
}
\value{
A named list with elements \code{username} and \code{server}, returned
invisibly.
}
\description{
\code{htc_config()} creates or reads an \code{htc.cfg} file that stores the
connection details needed by \code{htc_stage()}, \code{htc_submit()},
\code{htc_status()}, and \code{htc_fetch_results()}. On first use it prompts
interactively for your username and server address, writes \code{htc.cfg}
to \code{path}, and adds it to \code{.gitignore}. Subsequent calls read the
existing file.
}
\section{SSH connection reuse}{

Each call to \code{htc_stage()}, \code{htc_submit()}, \code{htc_status()}, or
\code{htc_fetch_results()} opens a new SSH connection to the submit server,
which triggers a Duo MFA prompt each time. You can avoid this by
configuring SSH connection reuse (ControlMaster) in your
\verb{~/.ssh/config} file. Add the following block:

\if{html}{\out{<div class="sourceCode">}}\preformatted{Host *.chtc.wisc.edu
  ControlMaster auto
  ControlPersist 2h
  ControlPath ~/.ssh/connections/\%r@\%h:\%p
}\if{html}{\out{</div>}}

Then create the connections directory:

\if{html}{\out{<div class="sourceCode bash">}}\preformatted{mkdir -p ~/.ssh/connections
}\if{html}{\out{</div>}}

After this, only the first connection in a two-hour window will
require Duo authentication. Full documentation:
\url{https://chtc.cs.wisc.edu/uw-research-computing/configure-ssh}
}

\section{Security}{

\code{htc.cfg} contains your username and server address. Neither is
sensitive on its own, but \code{htc_config()} adds \code{htc.cfg} to
\code{.gitignore} on creation to avoid accidentally committing
institutional account details to a public repository.
}

\examples{
\donttest{
# Preview what htc_config() would return without writing any files
cfg <- list(username = "netid", server = "ap2002.chtc.wisc.edu")
str(cfg)
}

\dontrun{
# Interactive first-time setup
cfg <- htc_config()

# Non-interactive setup (for scripts)
cfg <- htc_config(
  username = "erwin.lares",
  server   = "ap2002.chtc.wisc.edu"
)

# Force recreation of htc.cfg
cfg <- htc_config(overwrite = TRUE)

# Use in other functions
htc_upload(files = c("job.sub", "job.sh"), config = cfg)
}
}
