Skip to content

Commit

Permalink
http/cookies: split up into multi pages
Browse files Browse the repository at this point in the history
  • Loading branch information
bagder committed Jun 18, 2024
1 parent c699d4f commit cb560be
Show file tree
Hide file tree
Showing 6 changed files with 85 additions and 74 deletions.
4 changes: 4 additions & 0 deletions SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,10 @@
* [User-agent](http/modify/user-agent.md)
* [HTTP PUT](http/put.md)
* [Cookies](http/cookies/README.md)
* [Cookie engine](http/cookies/engine.md)
* [Reading cookies from file](http/cookies/reading.md)
* [Writing cookies to file](http/cookies/writing.md)
* [New cookie session](http/cookies/newsession.md)
* [Cookie file format](http/cookies/fileformat.md)
* [HTTPS](http/https.md)
* [HSTS](http/https/hsts.md)
Expand Down
79 changes: 5 additions & 74 deletions http/cookies/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,77 +19,8 @@ of the browser used to view a site. When you close the browser, you end your
session. Doing HTTP operations with a command-line client that supports
cookies begs the question of when a session really ends…

## Cookie engine

The general concept of curl only doing the bare minimum unless you tell it
differently makes it not acknowledge cookies by default. You need to switch on
the cookie engine to make curl keep track of cookies it receives and then
subsequently send them out on requests that have matching cookies.

You enable the cookie engine by asking curl to read or write cookies. If you
tell curl to read cookies from blank named file, you only switch on the engine
but start off with an empty internal cookie store:

curl -b "" http://example.com

Just switching on the cookie engine, getting a single resource and then
quitting would be pointless as curl would have no chance to actually send any
cookies it received. Assuming the site in this example would set cookies and
then do a redirect we would do:

curl -L -b "" http://example.com

## Reading cookies from file

Starting off with a blank cookie store may not be desirable. Why not start off
with cookies you stored in a previous fetch or that you otherwise acquired?
The file format curl uses for cookies is called the Netscape cookie format
because it was once the file format used by browsers and then you could easily
tell curl to use the browser's cookies.

As a convenience, curl also supports a cookie file being a set of HTTP headers
that set cookies. It is an inferior format but may be the only thing you have.

Tell curl which file to read the initial cookies from:

curl -L -b cookies.txt http://example.com

Remember that this only *reads* from the file. If the server would update the
cookies in its response, curl would update that cookie in its in-memory store
but then eventually throw them all away when it exits and a subsequent invocation
of the same input file would use the original cookie contents again.

## Writing cookies to file

The place where cookies are stored is sometimes referred to as the cookie
jar. When you enable the cookie engine in curl and it has received cookies,
you can instruct curl to write down all its known cookies to a file, the
cookie jar, before it exits. It is important to remember that curl only
updates the output cookie jar on exit and not during its lifetime, no matter
how long the handling of the given input takes.

You point out the cookie jar output with `-c`:

curl -c cookie-jar.txt http://example.com

`-c` is the instruction to *write* cookies to a file, `-b` is the instruction
to *read* cookies from a file. Oftentimes you want both.

When curl writes cookies to this file, it saves all known cookies including
those that are session cookies (without a given lifetime). curl itself has no
notion of a session and it does not know when a session ends so it does not
flush session cookies unless you tell it to.

## New cookie session

Instead of telling curl when a session ends, curl features an option that lets
the user decide when a new session *begins*.

A new cookie session means that all the old session cookies are be thrown
away. It is the equivalent of closing a browser and starting it up again.

Tell curl a new cookie session starts by using `-j, --junk-session-cookies`:

curl -j -b cookies.txt http://example.com/

* [Cookie file format](fileformat.md)
* [Cookie engine](engine.md)
* [Reading cookies from file](reading.md)
* [Writing cookies to file](writing.md)
* [New cookie session](newsession.md)
* [Cookie file format](fileformat.md)
20 changes: 20 additions & 0 deletions http/cookies/engine.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Cookie engine

The general concept of curl only doing the bare minimum unless you tell it
differently makes it not acknowledge cookies by default. You need to switch on
the cookie engine to make curl keep track of cookies it receives and then
subsequently send them out on requests that have matching cookies.

You enable the cookie engine by asking curl to read or write cookies. If you
tell curl to read cookies from blank named file, you only switch on the engine
but start off with an empty internal cookie store:

curl -b "" http://example.com

Just switching on the cookie engine, getting a single resource and then
quitting would be pointless as curl would have no chance to actually send any
cookies it received. Assuming the site in this example would set cookies and
then do a redirect we would do:

curl -L -b "" http://example.com

15 changes: 15 additions & 0 deletions http/cookies/newsession.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# New cookie session

A cookie as set by the server can be a *session cookie*, that is meant to be
kept around only for as long as the *session* lasts. curl has no idea how long
a session is or when it ends.

Instead of telling curl when a session ends, curl features an option that lets
the user decide when a new session *begins*.

A new cookie session means that all the old session cookies are be thrown
away. It is the equivalent of closing a browser and starting it up again.

Tell curl a new cookie session starts by using `-j, --junk-session-cookies`:

curl -j -b cookies.txt http://example.com/
20 changes: 20 additions & 0 deletions http/cookies/reading.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Reading cookies from file

Starting off with a blank cookie store may not be desirable. Why not start off
with cookies you stored in a previous fetch or that you otherwise acquired?
The file format curl uses for cookies is called the Netscape cookie format
because it was once the file format used by browsers and then you could easily
tell curl to use the browser's cookies.

As a convenience, curl also supports a cookie file being a set of HTTP headers
that set cookies. It is an inferior format but may be the only thing you have.

Tell curl which file to read the initial cookies from:

curl -L -b cookies.txt http://example.com

Remember that this only *reads* from the file. If the server would update the
cookies in its response, curl would update that cookie in its in-memory store
but then eventually throw them all away when it exits and a subsequent invocation
of the same input file would use the original cookie contents again.

21 changes: 21 additions & 0 deletions http/cookies/writing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Writing cookies to file

The place where cookies are stored is sometimes referred to as the cookie
jar. When you enable the cookie engine in curl and it has received cookies,
you can instruct curl to write down all its known cookies to a file, the
cookie jar, before it exits. It is important to remember that curl only
updates the output cookie jar on exit and not during its lifetime, no matter
how long the handling of the given input takes.

You point out the cookie jar output with `-c`:

curl -c cookie-jar.txt http://example.com

`-c` is the instruction to *write* cookies to a file, `-b` is the instruction
to *read* cookies from a file. Oftentimes you want both.

When curl writes cookies to this file, it saves all known cookies including
those that are session cookies (without a given lifetime). curl itself has no
notion of a session and it does not know when a session ends so it does not
flush session cookies unless you tell it to.

0 comments on commit cb560be

Please sign in to comment.